NAME
orac_Base.pm - the base class for all database modules of the Orac tool
DESCRIPTION
This code is the base database object that can be created by the Orac tool. It has all the basic data and methods. Many of those are empty (do nothing) methods to be overridden, some are inherited and used as is.
PUBLIC METHODS
&Dump()
&about_orac()
&add_contents()
&balloon_bar()
&create_button_bar()
&create_balloon_bars()
&do_a_generic()
&db_check_error()
&do_query()
&do_query_fetch1()
&do_query_fetch_all()
&double_click_message()
&f_clr()
&f_str()
&generic_hlist()
&get_frm()
&get_img()
&get_lines()
&gf_str()
&init1()
&init2()
&live_update()
&must_f_clr()
&need_ps()
&need_sys()
&new()
&orac_image_label()
&post_process_sql()
&print_lines()
&print_stack()
&see_gif()
&see_plsql()
&see_sql()
&see_sql_but()
&show_or_hide()
&show_sql()
&stop_live_update()
&top_left_message()
&top_right_ball_message()
&window_exit_button()
new
Start documenting here next time...
show_sql
Take some SQL, execute it, format the results in a matrix-like style, and show it in the Text_var widget.
ARG1 = the SQL file name (main part, e.g. "Threads")
ARG2 = the SQL level number (e.g. 1)
ARG3 = a title (optional, if not sent, the first 40 chars of the SQL is used)
ARG4 = optional bind parameters array (note: array not ref to array)
There is no return value.
array do_query_fetch1(statement)
This subroutine takes an SQL statement (a select) as ARG 1, executes it, fetches the 1 row as the answer, and returns that row as an array for the answer. If it fails, it dies.
This is useful for those times you KNOW you're getting back a single row, or even a single value; e.g. a count.
Example: ($count) = do_query_fetch1("select count(*) from table");
live_update
Take some SQL, execute it, format the results in a matrix-like style, and show it in the Text_var widget (just like show_sql :-) AND do it once a second until the user presses the Stop button.
ARG1 = the SQL file name (main part, e.g. "Threads")
ARG2 = the SQL level number (e.g. 1)
ARG3 = a title (optional, if not sent, the first 40 chars of the SQL is used)
There is no return value.
Note: it may take 1 or 2 seconds for the process to register the stop after the user presses Stop. Not sure how to fix this; probably can't as the GUI will most likely be sleeping when the button is actually pressed, so it'll take a second or so for the button press to be found.:w
EXPERIMENTAL METHODS
These functions are ones that I'm developing and should not be called by anyone else, unless you like living dangerously. :-) It is hoped that one day, they'll be good enough to move into orac_Base.
&generic_hlist()
&sql_file_exists()
Andy, you can move this if you want. (i.e. feel brave :-)
generic_hlist
A function to produce a dialog screen, with HList widget to show data--all generic. It will go down as many levels as there are SQL files, which must be numbered sequentially.
The function executes the SQL, and expects either a set of rows with 1 column each, or 1 row with a set of columns. It takes the data, and makes each value an item in the HList widget. If it can find another level below this SQL script, it gives the item a "folder" looking icon, else just a "file" looking icon.
Clicking on closed folders executes the next level of SQL, and displays the results in the HList widget. Icons on the new level are assigned as above. The value clicked on is parsed, split by the separator char (ARG2) and those are the bind parameters to the SQL. It is assumed the SQL will take those and do the right thing. If there is a mismatch on number of bind parameters, an error will occurr. [Implementation question: should we search the SQL and get the number of placeholders and send only that number of parameters?]
Clicking on a file, or bottom level item, currently does nothing. [Implementation question: should we put a function to be called in orac_Base here, and let the various modules override that if they want to do more than just show items?]
ARG1 = name of SQL, and title of dialog (e.g. Tables)
ARG2 = separator character
There is no return value.
Note: this functoin calls orac_Show(), therefore, it does not really return until the dialog is dismissed.
show_or_hide
A support function of generic_hlist, DO NOT CALL DIRECTLY!!!
This is called when an entry is double-clicked. It decides what to do. Basically ripped off from the "Adv. Perl Prog." book. :-)
add_contents
A support function of generic_hlist, DO NOT CALL DIRECTLY!!!
show_or_hide calls this when it needs to add new items. Here is where the SQL is called.
do_a_generic
A support function of generic_hlist, DO NOT CALL DIRECTLY!!!
show_or_hide calls this when it needs to add new items. The base, no nothing, version.
sql_file_exists
Does the SQL file exist? This is normally used to find out if there is another level down.
ARG1 = database type
ARG2 = SQL subroutine name (e.g. Tables, Views, ...)
ARG3 = level number
It returns TRUE (non-zero) if the file exists and is readable, FALSE otherwise.
post_process_sql
This subroutine is called with the results from show_sql() to allow DB modules to "post process" the output, if required, before it is analyzed to be shown. This is useful for turning numeric flags into words, and other such DB dependent things. This generic one does NOTHING!
create_button_bar
This creates a generic bar for placing active screen buttons upon.
create_balloon_bars
This creates the necessary basic requirements for setting up message balloons within a status bar.
see_sql_but
This creates a basic 'See SQL' button for viewing executed SQL.
window_exit_button
This creates a basic 'Exit' button for leaving a window. It destroys the window it is set upon.
double_click_message
For helpful "Double-click" messages, at the tops of screens, use this function.
top_left_message
For 'top of the screen' left hand basic messages, this function is used.
top_right_ball_message
For 'top of the screen' right hand 'green-ball' type messages, use this basic function.
balloon_bar
Create the basic balloon bar for attaching balloon messages to.
orac_image_label
Create a label with the basic Orac image on it, and packs it to the right of a frame.
get_img
Gets a window and image reference, and a file name, and fills the image variable with the desired image.