Andy Duncan > Orac-alpha > orac_Base

Download:
Orac-alpha-1.2.6.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Source  

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.

syntax highlighting: