HandyKit v2.1  

 Online
 Index page
 HowTo

HandyKIT packages

 HandyCGI.pm
 HandyList.pm
 HandyMail.pm
 HandyTemplate.pm
 HandyTextDB.pm
 SiteBag.pm

Other packages

 HandySQL.pm
 HandyLog.pm
 HandyCrypt.pm

NAME

HandySQL - a package that is very handy to be be used for regular MySQL access.


SYNOPSIS

use HandySQL;
        
# connection is made on demand to 
# database by configuration, specified
# in config file

$descr = &describe_table("tablename");

# now $descr is reference to array, that contains 
# names of each column, that is hold inside of the 
# table `tablename'

$nm = &get_rows("tablename", 
  "where clause", "order by", 
  limit, ofs)

# retrieves an nmtable object, that is got, by using 
# of statement SELECT * FROM tablename WHERE where 
# clause ORDER BY order by LIMIT ofs,limit
# get_rows can also be called in these ways:

$nm = &get_rows("tablename", 
  "where clause", "order by", limit);
$nm = &get_rows("tablename", 
  "where clause", "order by");
$nm = &get_rows("tablename", 
  "where clause");
$nm = &get_rows("tablename");

# please consider, that doing last query can 
# result in enormously big table, and perl 
# will drop a core dump.

$rows_updated = &update_rows("tablename", 
  "where clause", 
    { 'field_1' => &str_sqlize('alpha'), 
      'field_2' => '1' 
    } );

# this will generate UPDATE statement for supplied 
# parameters. if 0 rows are updated '0E0' is returned.

$rows_updated = &insert_rows("tablename",
  { 'field_1' => &str_sqlize('alpha'), 
    'field_2' => '1' 
  } );

# this will generate UPDATE statement for supplied 
# parameters.

$rows_updated = &delete_rows("tablename", 
  "where clause");

# this will generate UPDATE statement for supplied 
# parameters. all these functions returns number of 
# rows affected.


CONFIGURATION

config.pm
We encourage you to store all your project configuration data in config module inside of hash %cfg. All configuration for HandyCGI, HandyTemplate, HandySQL, HandyLog, HandyMail and HandyList modules are stored in this file by default. However, if you dislike this approach feel free to modify code a little.

dbdebug
Set it to 1 if you want to log all SQL transactions to regular log file, that is written by HandyLog module. Otherwise set it to 0 or don't set at all.

connection_timeout
If module was unable to connect to database, it will retry after sleeping one second. Specify here amount of seconds that this module will try to reconnect with MySQL server.

dbhost
Hostname or IP address of MySQL server.

dbuser
Username that is accessing MySQL server.

dbpass
Password that is used in access to MySQL server.

dbname
Name of the database.

dblog
Optional. If not set to undef, then it could contain path to a file, where all database transactions will be stored. Useful to create backups of database.

lock_timeout
The time used to time out in &sql_lock subroutine.


DESCRIPTION

General behaviour
Module on demand connects to DB, using parameters that are specified in config file, if it fails to connect - it writes logs and bails out. If local variable $debug is equal to 1, then all database usage will be logged into a log files. This module is designed to connect exactly to ONE database. Why? Just to make programming extremly handy. MOST of request of web program is done to one database.

$nm = get_rows($tablename, $where, $orderby, $lim, $ofs)
Returns an $nm table with named columns by using select statement. $nm has structure: $nm is a reference to array of rows. $nm->[i] is a reference to a hash, which corresponds to i-th row. $nm->[i]->{'colname'} is a data in i-th row, in column named colname.

Statement is composed by this algorythm:

SELECT * FROM $tablename [WHERE $where] 
                         [ORDER BY $orderby]
                         [LIMIT [$ofs,]$lim]

If $orderby or $where is equal to '' the function considers as they're absent.

$fields = get_row($tablename, $where, $orderby, $lim, $ofs)
Returns a $fields reference to a hash by using select statement. This function returns exactly ONE row.

Statement is composed by this algorythm:

SELECT * FROM $tablename [WHERE $where] 
                         [ORDER BY $orderby]
			 LIMIT [$ofs,] 1

If $orderby or $where is equal to '' the function considers as they're absent, so you can specify $ofs without where and orderby clauses.

$rows_affected = update_rows($tablename,$where,$fields)
Launches UPDATE statement on table $tablename, by using $where clause, while setting data to specified by $fields (reference to a hash). Please, consider, that absent $tablename, $where and/or $fields are errors. Returns how many rows affected. '0E0' is returned if zero affected.

$rows_affected = delete_rows($tablename,$where)
Launches DELETE statement on table $tablename, by using $where clause. Please, consider, that absent $tablename and/or $where are errors. Returns how many rows affected.

$rows_affected = insert_rows($tablename,$fields)
Launches INSERT statement on table $tablename, by inserting a row specified by $fields (reference to a hash). Please, consider, that absent $tablename and/or $fields are errors. Returns how many rows affected.

$rows_affected = insert_rows_ifne($tablename,$fields)
Does the same as insert_rows, but doesn't print error message into log file, if inserted item already existed in database.

$table = do_query($query)
Should be used to launch queries. Generally, $query will contain SELECT statement. The return value is a reference to array of references to array of values. Use make_nmtable to make output like in get_rows. Here is example:

$table = &do_query("SELECT a.column_a,b.column_b 
			 from a,b where a.column_c = b.column_c");
&make_nmtable($table,['column_a','column_b']);

After make_nmtable call the $table will be a reference to array of references to a hash, where actual values are stored.

$sqlstr = str_sqlize($str)
Converts $str to into SQL string format. If $str eq 'Somebody's test', then $sqlstr eq "\'Somebody\'s test\'".

$str = str_unsqlize($str)
Action is a reversed str_sqlize.

$timestamp = sql_date($time)
Returns datetime in form YYYYMMDDHHMMSS from $time seconds. Current datetime is &sql_date(time). But use of now() builtin of SQL is encouraged. Consider, that time on hosts which runs CGI-scripts and MySQL server could be different.

$time = sql_ts2sec($timestamp)
Converts timestamp (YYYYMMDDHHMMSS) to seconds. &sql_ts2sec(&sql_date($x)) == $x.

$timestamp = sql_date2ts($date)
Converts date from format YYYY-MM-DD to YYYYMMDD000000.

$date = sql_ts2date($timestamp)
Converts timestamp (YYYYMMDDHHMMSS) to date YYYY-MM-DD.

$time = sql_ts2time($timestamp)
Converts timestamp (YYYYMMDDHHMMSS) to time HH:MM:SS

push_a_nmtable($nmt,$dbt,$value)
$nmt,$dbt,$value is references to arrays. This function typically does:
1. Converts @$value to a hash, which contains elements of @$dbt as keys and corresponding elements of @$value as values. Imagine this, as you ``name'' elements of @$value in correspondance with @$dbt.
2. Pushes resulting reference to a hash into @$nmt array.

So $nmt is a reference to array of refferences to hashes. I call them ``named tables''. Typical dereference is: $nmt->[$i]->{$column_name} Where $i is row number, and $column_name is the name of database column. Very handy.

make_nmtable($nmt,$dbt)
$nmt is a reference to array of references to array. Typically retrieved undescriben data from database by &do_query subroutine. $dbt is a column names (ref to array). It produces $nmt similar to describen in push_a_nmtable.



TOP
© 2000 || Perl4YOU.com E-mail: info@perl4you.com