/ 
sparky-public-1.06
/ Sparky::Public

NAME

Sparky::Public - support functions for Sparky data collector and profiler

SYNOPSIS

use Sparky::Public;

if ($line =~ /$datestamp/i) { ... }

$secs = $tim * SEC/TIM;

$time = waitfor($number);
$time = waitfor($string);

trcfilter($sid, $ost0, $ost1, $dbt0, $dbt1, $ofile, @ifiles);

$t = hstr2time($string);
$str = htime2str($fmt, $time, $digits);

checkenv(@envvars);

printf "%8s\n", fnum($text, $precision);

$min = min(@list);
$max = max(@list);

DESCRIPTION

$datestamp

$datestamp is a regular expression that matches the date stamp that an Oracle session prints to its trace file.

TIM, SEC

TIM is the number of Oracle clock ticks per second. SEC is unity (the number of seconds per second). We provide SEC so that the programmer may refer naturally to SEC/TIM or TIM/SEC in code that requires unit conversions.

waitfor
$time = waitfor($number);
$time = waitfor($string);

waitfor() waits until a specified event occurs before returning control to its caller. The return value in all cases is the time (in seconds since the Epoch) at which control was returned to the caller. If its argument is undefined, then it returns control immediately to its caller.

If the argument to waitfor() is a whole number (matching the pattern /\d+/), then it is assumed to be a time (in seconds since the Epoch) at which control is to be returned to the caller. If $number represents a time in the past, then waitfor() returns control immediately to its caller.

If the argument to waitfor() is defined but does not match the purely numeric pattern discussed previously, then the argument is assumed to be an interactive prompt. First, waitfor() will determine whether STDERR and STDIN are tty devices. If they are tty devices, then waitfor() will prompt STDERR with the interpolated string "Press a key$string..." and await a keypress on STDIN. Upon receiving a keypress, waitfor() will complete the prompt line by writing the keypress time followed by "\n" to STDERR. If STDERR and STDIN are not tty devices, then waitfor() will return immediately.

The waitfor() function is designed to simplify the specification of performance analysis observation intervals defined in real-time. This example shows how to use waitfor() to define an observation interval interactively:

# interactive style
$t0 = waitfor(" to begin observation interval");
# take a snapshot
$t1 = waitfor(" to end observation interval  ");
# take a snapshot
printf "Observation interval duration: %.3f sec\n", $t1-$t0;

The resulting session will look like this:

Press a key to begin observation interval...(Thu Apr  5 16:36:19 2001)
Press a key to end observation interval  ...(Thu Apr  5 16:36:20 2001)
Observation interval duration: 1.168 sec

The waitfor() function can also be used as an alternative to at(1) or cron(1M), which can be especialy helpful on systems without adequate scheduling facilities:

# batch style
use Date::Parse;
for (7..18) {
    my $t0 = scalar localtime str2time("$_:00");
    waitfor(str2time($time));
    ...
}

The resulting session will take a snapshot every hour upon the hour from 7:00am through 6:00pm (07.00-18.00).

trcfilter
trcfilter($sid, $ost0, $ost1, $dbt0, $dbt1, $ofile, @ifiles);

<trcfilter> employs Hotsos research results to filter Oracle trace files created by event 10046 level 1, 4, 8, or 12. The input file filtration criterion is a time range, expressed as observation interval beginning and ending times on two separate clocks.

The first clock is the OS time clock, recorded in Epoch seconds and fractions of seconds. $ost0 and $ost1 are interval beginning and end times, respectively. The second clock is the database time clock, as recorded in v$timer.hsecs, and converted to seconds and fractions of seconds. $dbt0 and $dbt1 are the db clock times that correspond to $ost0 and $ost1. trcfilter equates the t0 times of these two clocks.

$ofile is the name of the file to which the filtered trace data will be written. The first file named in the @ifiles list is the name of the input trace file to be filtered.

$sid is presently only a placeholder. In a future revision of trcfilter, this parameter will denote the id of the session whose trace data may be scattered across multiple input files by using Oracle's Multi-Threaded Server option (hence the reason that @ifiles is a list, and not a scalar).

trcfilter passes the trace file preamble unaltered. For trace file lines that represent events that cross a time interval boundary, trcfilter emits a line whose elapsed and CPU times (where applicable) are adjusted to reflect only the duration that exists within the specified observation interval. trcfilter emits all "PARSING IN CURSOR" actions that occur before $ost0 (or, equivalently, before $dbt0). It emits all "STAT" actions that occur after $ost1 ($dbt1).

hstr2time
$t = hstr2time($string);

hstr2time sits atop the Date::Parse str2time function call. If $string has a fraction-of-a-second component, hstr2time will preserve that information in its return value.

htime2str
$str = htime2str($fmt, $time, $digits);

htime2str sits atop the Date::Format time2str function call. $digits is an integer defining the number of digits past the decimal point that should be included in the string return value.

checkenv
checkenv(@envvars);

checkenv tests to ensure that a list of OS environment variables are set. If one or more variables are unset, then checkenv will print a warning about each unset variable and then exit with a call to die.

fnum
printf "%8s\n", fnum($text, $precision);

fnum returns $text in a friendly format with commas as thousands separators, and with $precision digits to the right of the decimal point.

min, max
$min = min(@list);
$max = max(@list);

min returns the numerically smallest element of a list, and max returns the numerically largest element of a list.

ENVIRONMENT

Many Sparky::Public modules require that $main::program be set to the name of the calling executable program. It is usually set with $main::program = basename $0.

If the value $main::opt{v} is set, then many Sparky::Public functions will print verbose information.

AUTHOR

Cary Millsap, cary.millsap@hotsos.com.

SEE ALSO

perl(1).