MAN page from Old RedHat 7.X perl-Simran-DB-Session-1.2-8.i386.rpm
Session
Section: User Contributed Perl Documentation (3)
Updated: perl v5.6.0
Index NAME
DB_session.pm - Database Session
##################################################################################################################
DESCRIPTION
Gives a friendlier interface to the
DBI module.
##################################################################################################################
SYNOPSIS
Please see
DESCRIPTION.
##################################################################################################################
REVISION
$Revision: 1.2 $
$Date: 2000/04/26 04:28:08 $
##################################################################################################################
AUTHOR
Simran
simranAATTunsw.edu.au##################################################################################################################
BUGS
No known bugs.
##################################################################################################################
PROPERTIES
DATABASE: the name of the database to connect to.
HOST: the name of the host computer for the session.
PORT: the port number to connect to the host.
USERNAME: the user name to use for the connection.
PASSWORD: the password to use for the connection.
DSN: the Data Source Name.
PROTOCOL: the protocol to use for DBI. Defaults to ``mysql''
DATABASE_HANDLE: the database handle when the connection is made (used to perform queries etc).
##################################################################################################################
METHODS
##################################################################################################################
new
- Description
- This is the create method for the DB_session class. The new method can becalled with parameters, if it is, they ar passed to the set method (seebelow).
$session = DB_session->new
or
$session = DB_session->new($parameters)
eg. $session = DB_session->new("PROTOCOL=mysql;DATABASE=test;HOST=localhost;PORT=3306");
- Input
$parameters - the parameters string is passed straight to the set method (see below).
- Output
New DB_session object created.
- Return Value
New DB_session object.
##################################################################################################################
set
- Description
- This method takes strings (one or more) of the form ``<property1>=<value1>;<property2>=<value2>'' (i.e. each value in the same string must beseparated by a semi colon). And sets the coressponding property in theobject.
Example: to set the DATABASE property $session->set(``DATABASE=MyDataBase'')
set is case insensitive when working out which property to set (egDATABASE or database) would work equally well.
$session->set(@parameters); # list of parameter strings
or
$session->set($parameters); # single parameter string
- Input
@parameters (list of inputs $parameters below)
$parameters (scalar, string) - the parameters string (or list of strings is a set of paired <property>=<value>, with each pair being separated by a semi-colon.
Note: Dont use semi-colons or equals (; or =) in the values
eg: $parameters = "DATABASE=MyData;USER=Me;PASSWORD=secret";
- Output
Sets properties within the object
- Return Value
returns 1 if all parameters successfully set.
##################################################################################################################
build_dsn
- Description
- This internal method builds the DSN property (needed for the connection). Thereshould be no need to call this manually as the DB_session object shouldinvoke this method interanlly whenever it needs to connect to the DB
A DSN looks like ``DBI:<protocol>:database=<dbname>;host=<hostname>;port=portname''. The host and the port are optional, but the protocol andthe database are essential.
- Syntax
$session->set(@parameters); # list of parameter strings
or
$session->set($parameters); # single parameter string
- Input
None, uses object properties
- Output
Builds the DSN property
- Return Value
returns 1 if DSN is valid.
##################################################################################################################
connect
- Description
- This method connects to the database using the DBI connect method.Needs a valid DSN to succeed and invokes the internal ``build_dsn'' method.This is mostly an internal method called when a conection becomesnecessary.
- Input
None, uses object properties DSN, USERNAME, PASSWORD
- Output
creates DBI database handle and stores it in the DATABASE_HANDLE property.
- Return Value
returns 1 if connection succeeds.
##################################################################################################################
disconnect
- Description
- This method disconnects the database handle using the DBI disconnect method.This can be called explicity, but will be called when the DB_session objectis destroyed. ie. when the object is removed or deleted.
$session->disconnect
- Input
None, uses object property DATABASE_HANDLE
- Output
Disconnects and removes the DATABASE_HANDLE
- Return Value
1 if the disconnection succeeds
##################################################################################################################
query_handle
- Description
- Returns a statement handle of a particular query (see DBI and DBDdocumentation for how to use the query handle. The query handle should beexplictly closed ($handle->finish) to avoid warnings and errors.
eg.
$handle = $query_handle($query);
- Input
$query - the sql query to use
- Output
$handle - the statement handle
- Return Value
same as output
##################################################################################################################
quote
- Description
- Puts escape characters next to charaters for sql strings (queries etc).
The following characters have an escape '\' put in front of them:", ', \, !, \t, \r, \n, \0,
In addition if a positive second parameter is sent (for stronger'literal' escaping) these characters are escaped: %, <, >, =
$escaped_string = $session->escape($string); or
$escaped_string = $session->escape($string, 1); (for literal)
- Input
$string - the string to 'quote'
1 (optional) if positive, stronger escaping used.
- Output
$escaped_string
- Return Value
none
##################################################################################################################
all_values
- Description
- Similar to the 'Value' from db_routines.pl function, but returns theentire query.
'all_values' does not keep the statement handle so once called, the query returnsthe results and then is gone.
$array_ref = $session->all_values($query);
- Input
$query - the sql query to run
- Output
$array_ref - the result of a 'fetchall_arrayref'
- Return Value
output is the return value.
##################################################################################################################
rarh
- Description
- Used for accessing the data from the database with a special output/return value
$url_data = $dbObject->rarh("table", "id=$id and name='simran'")
- Input
$table - the table name we are to get data from $where_clauses - any where clauses
- Output
$table_data - the output is a "reference to an array of references to hashes" containing information for data associated with the query. eg. $table_data = [ { row1field1 => row1value1, row1field2 => row1value2, ... } { row2field1 => row2value1, row2field2 => row2value2, ... } ] Note: All the field names will be in lower case.
- Return Value
Same as output.
##################################################################################################################
value
- Description
- Equivalent to the 'Value' from db_routines.pl function, but returns theentire query.
'values' does not keep the statement handle so once called, the query returnsthe results and then is gone.
eg.
@array = $session->value($query);
- Input
$query - the query string...
- Output
@array - the result of a 'fetchrow'
- Return Value
output is the return value.
##################################################################################################################
do
- Description
- A fairly generic do command for the database. It connects if necessaryand executes the command. It returns the number of row effected by thecommand.
eg.
$rows = $session->do($mysql_command);
- Input
$mysql_command (scalar, string) a command to be executed using the DBI::do method.
- Output
$rows (scalar, integer) the number of rows affected. If do method fails rows will be 'undef' # if the method succeeds but the command effects no rows the return value will be 0.
- Return Value
same as output
##################################################################################################################
error
- Description
- If called in an array context, returns the complete history of error messagesthus far. Else, returns the latest error message if set.
$errmsg = $session->error();
or
foreach $_ ($session->error()) { print "Error: $_\n"; }
- Input
none
- Output
In array context, returns an array containing all error message set thus far. Else, returns the latest error message if set.
- Return Value
same as output
##################################################################################################################
DESTROY
- Description
- The automatic destructor method for DB_session. Called automatically whena DB_session is destroyed.
- Syntax
not used. method called when object is destroyed
- Input
none
- Output
none
- Return Value
none
Index
- NAME
- DESCRIPTION
- SYNOPSIS
- REVISION
- AUTHOR
- BUGS
- PROPERTIES
- METHODS
- new
- set
- build_dsn
- connect
- disconnect
- query_handle
- quote
- all_values
- rarh
- value
- do
- error
- DESTROY
This document was created byman2html,using the manual pages.
