Difference between revisions of "API:EPrints/Database"

From EPrints Documentation
Jump to: navigation, search
 
(30 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
+
This page has been automatically generated from the EPrints 3.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Database.pm|package_name=EPrints::Database}}[[Category:API|DATABASE]][[Category:API:EPrints/Database|DATABASE]]<div><!-- Edit below this comment -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Database.pm|package_name=EPrints::Database}}[[Category:API|DATABASE]]<div><!-- Edit below this comment -->
  
  
Line 21: Line 21:
 
Provides access to the backend database. All database access done via this module, in the hope that the backend can be replaced as easily as possible.
 
Provides access to the backend database. All database access done via this module, in the hope that the backend can be replaced as easily as possible.
  
The database object is created automatically when you start a new eprints session. To get a handle on it use:
+
In most use-cases it should not be necessary to use the database module directly. Instead you should use [[API:EPrints/DataSet|EPrints::DataSet]] or  [[API:EPrints/MetaField|EPrints::MetaField]] accessor methods to access objects and field  values respectively.
 
 
$db = $session-&gt;get_database
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 34: Line 32:
 
<!-- Pod2Wiki=head_cross_database_support -->
 
<!-- Pod2Wiki=head_cross_database_support -->
 
===Cross-database Support===
 
===Cross-database Support===
Any use of SQL must use quote_identifier to quote database tables and columns. The only exception to this are the Database::* modules which provide database-driver specific extensions.
+
Any use of SQL statements must use [[API:EPrints/Database#quote_identifier|quote_identifier]] to quote database tables and columns and quote_value to quote values. The only exception to this are the EPrints::Database::* modules which provide database-driver specific extensions.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_quoting_sql_values -->
 +
===Quoting SQL Values===
 +
By convention variables that contain already quoted values are  prefixed with <tt>Q_</tt> so they can be easily recognised when used in  string interpolation:
 +
 
 +
my $Q_value = $db-&gt;quote_value( "Hello, World!" );
 +
$db-&gt;do("SELECT $Q_value");
 +
 
 +
Where possible you should avoid quoting values yourself, instead use a  method that accepts unquoted values which will (safely) do the work  for you.
  
Variables that are database quoted are prefixed with 'Q_'.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_constants -->
 +
==CONSTANTS==
 +
All the <tt>SQL_</tt> column types defined by Perl module {{API:PodLink|file=DBI|package_name=DBI|section=|text=DBI}} and the  following:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 45: Line 68:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=head_methods -->
+
<!-- Pod2Wiki=item_sql_null -->
==METHODS==
+
===SQL_NULL===
 +
 
 +
A column value is undefined.
 +
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 54: Line 80:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_build_connection_string -->
+
<!-- Pod2Wiki=item_sql_not_null -->
===build_connection_string===
+
===SQL_NOT_NULL===
 +
 
 +
A column value is defined.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$dbstr = EPrints::Database::build_connection_string( %params )
 
Build the string to use to connect to the database via DBI. %params  must contain dbname, and may also contain dbport, dbhost and dbsock.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_instance_variables -->
 +
==INSTANCE VARIABLES==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 67: Line 101:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create -->
+
<!-- Pod2Wiki=item_$self->{session} -->
===create===
+
===$self-&gt;{session}===
  
  $db = $db-&gt;create( $username, $password )
+
The [[API:EPrints/Session|EPrints::Session]] which is associated with this database connection.
Create and connect to a new database using super user account $username and $password.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 80: Line 113:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_new -->
+
<!-- Pod2Wiki=item_$self->{debug} -->
===new===
+
===$self-&gt;{debug}===
  
$db = EPrints::Database-&gt;new( $session )
+
If <tt>true</tt> then SQL is logged.
Create a connection to the database.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 93: Line 125:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_connect -->
+
<!-- Pod2Wiki=item_$self->{dbh} -->
===connect===
+
===$self-&gt;{dbh}===
  
$foo = $db-&gt;connect
+
The handle on the actual database connection.
Connects to the database.  
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 106: Line 137:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_disconnect -->
+
<!-- Pod2Wiki=head_methods -->
===disconnect===
+
==METHODS==
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$foo = $db-&gt;disconnect
 
Disconnects from the EPrints database. Should always be done before any script exits.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_database -->
 +
===Database===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 119: Line 155:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_error -->
+
<!-- Pod2Wiki=item_new -->
===error===
+
====new====
 +
 
 +
$db = EPrints::Database-&gt;new( $repo, [ %opts ] )
 +
Create a connection to the database.
  
$errstr = $db-&gt;error
+
Options:
Return a string describing the last SQL error.
+
  db_connect - Boolean. Also connect to the database (default: true).
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 132: Line 171:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_begin -->
+
<!-- Pod2Wiki=item_create -->
===begin===
+
====create====
  
  $db-&gt;begin
+
  $db = $db-&gt;create( $username, $password )
Begin a transaction.
+
Create and connect to a new database using user account <tt>$username</tt>  and <tt>$password</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 145: Line 184:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_commit -->
+
<!-- Pod2Wiki=item_build_connection_string -->
===commit===
+
====build_connection_string====
 +
 
 +
$dbstr = EPrints::Database::build_connection_string( %params )
 +
Build the string to use to connect to the database via {{API:PodLink|file=DBI|package_name=DBI|section=|text=DBI}}.
  
  $db-&gt;commit
+
Parameters:
Commit the previous begun transaction.
+
dbname - Database name (REQUIRED).
 +
dbdriver - Database driver (e.g. mysql, Oracle, pgsql, default: mysql).
 +
  dbhost - Database host.  Assumes localhost if unset.
 +
dbport - Port to connect to database host.  Assumes default for driver if unset.
 +
dbsock - Socket file to connect to database through.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 158: Line 204:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_rollback -->
+
<!-- Pod2Wiki=item_connect -->
===rollback===
+
====connect====
  
  $db-&gt;rollback
+
  $db-&gt;connect()
Rollback the partially completed transaction.
+
Connects to the database.  
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 171: Line 217:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_archive_tables -->
+
<!-- Pod2Wiki=item_disconnect -->
===create_archive_tables===
+
====disconnect====
  
  $success = $db-&gt;create_archive_tables
+
  $db-&gt;disconnect()
Create all the SQL tables for each dataset.
+
Disconnects from the EPrints database. Should always be done before  any script exits.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 184: Line 230:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_archive_tables -->
+
<!-- Pod2Wiki=item_set_debug -->
===drop_archive_tables===
+
====set_debug====
  
  $db-&gt;drop_archive_tables()
+
  $db-&gt;set_debug( $boolean )
Destroy all tables used by eprints in the database.
+
Set the SQL debug mode to <tt>true</tt> or <tt>false</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 197: Line 243:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_dataset_tables -->
+
<!-- Pod2Wiki=item_set_version -->
===create_dataset_tables===
+
====set_version====
  
  $success = $db-&gt;create_dataset_tables( $dataset )
+
  $db-&gt;set_version( $versionid );
Create all the SQL tables for a single dataset.
+
Set the version id table in the SQL database to the given <tt>versionid</tt> (used by the upgrade script).
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 210: Line 256:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_dataset_tables -->
+
<!-- Pod2Wiki=item_get_version -->
===drop_dataset_tables===
+
====get_version====
  
  $db-&gt;drop_dataset_tables( $dataset )
+
  $version = $db-&gt;get_version
Drop all the SQL tables for a single dataset.
+
Returns the current database schema version.  
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 223: Line 269:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_dataset_index_tables -->
+
<!-- Pod2Wiki=item_is_latest_version -->
===create_dataset_index_tables===
+
====is_latest_version====
  
  $success = $db-&gt;create_dataset_index_tables( $dataset )
+
  $boolean = $db-&gt;is_latest_version
Create all the index tables for a single dataset.
+
Return <tt>true</tt> if the SQL tables are in the correct configuration for this edition of eprints. Otherwise, <tt>false</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 236: Line 282:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_dataset_ordervalues_tables -->
+
<!-- Pod2Wiki=item_get_server_version -->
===create_dataset_ordervalues_tables===
+
====get_server_version====
  
  $success = $db-&gt;create_dataset_ordervalues_tables( $dataset )
+
  $version = $db-&gt;get_server_version
Create all the ordervalues tables for a single dataset.
+
Return the database server version.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 249: Line 295:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_type_info -->
+
<!-- Pod2Wiki=item_get_default_charset -->
===type_info===
+
====get_default_charset====
 +
 
 +
$charset = $db-&gt;get_default_charset
 +
Return the character set to use.
  
$type_info = $db-&gt;type_info( DATA_TYPE )
+
Returns <tt>undef</tt> if character sets are unsupported.
See {{API:PodLink|file=DBI|package_name=DBI|section=type_info|text=DBI/type_info}}.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 262: Line 310:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_column_type -->
+
<!-- Pod2Wiki=item_get_default_collation -->
===get_column_type===
+
====get_default_collation====
  
  $real_type = $db-&gt;get_column_type( NAME, TYPE, NOT_NULL, [ LENGTH/PRECISION ], [ SCALE ], %opts )
+
  $collation = $db-&gt;get_default_collation( $lang )
Returns a SQL column definition for NAME of type TYPE, usually something like:
+
Return the collation to use for language <tt>$lang</tt>.
  
  $name $type($length,$scale) [ NOT NULL ]
+
Returns <tt>undef</tt> if collation is unsupported.
 
 
If NOT_NULL is true column will be set "not null".
 
  
LENGTH/PRECISION and SCALE control the maximum lengths of character or decimal types (see below).
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
Other options available to refine the column definition:
 
  
  langid - character set/collation to use
+
<!-- Pod2Wiki= -->
  sorted - whether this column will be used to order by
+
</div>
 
+
<!-- Pod2Wiki=item_get_driver_name -->
'''langid''' is mapped to real database values by the "dblanguages" configuration option. The database may not be able to order the request column type in which case, if '''sorted''' is true, the database may use a substitute column type.
+
====get_driver_name====
  
TYPE is the SQL type. The types are constants defined by this module, to import them use:
+
$driver = $db-&gt;get_driver_name
 +
Return the database driver name.
  
  use EPrints::Database qw( :sql_types );
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
 
+
<span style='display:none'>User Comments</span>
Supported types (n = requires LENGTH argument):
+
<!-- Edit below this comment -->
  
Character data: SQL_VARCHAR(n), SQL_LONGVARCHAR.
 
  
Binary data: SQL_VARBINARY(n), SQL_LONGVARBINARY.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_error -->
 +
====error====
 +
 
 +
$errstr = $db-&gt;error()
 +
Return a string describing the last SQL error.
  
Integer data: SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT.
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
Floating-point data: SQL_REAL, SQL_DOUBLE.
 
  
Time data: SQL_DATE, SQL_TIME.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_retry_error -->
 +
====retry_error====
  
The actual column types used will be database-specific.
+
$boolean = $db-&gt;retry_error()
 +
Returns a boolean for whether the database error is a retry error.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 306: Line 364:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_table -->
+
<!-- Pod2Wiki=item_duplicate_error -->
===create_table===
+
====duplicate_error====
 +
 
 +
$boolean = $db-&gt;duplicate_error()
 +
Returns a boolean for whether the database error is a duplicate error.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$success = $db-&gt;create_table( $tablename, $dataset, $setkey, @fields );
 
Create the tables used to store metadata for this dataset: the main table and any required for multiple or mulitlang fields.
 
  
The first $setkey number of fields are used for a primary key.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_begin -->
 +
====begin====
 +
 
 +
$db-&gt;begin()
 +
Begin a transaction.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 321: Line 390:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_has_sequence -->
+
<!-- Pod2Wiki=item_commit -->
===has_sequence===
+
====commit====
 +
 
 +
$db-&gt;commit()
 +
Commit the previously begun transaction.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_rollback -->
 +
====rollback====
  
  $boolean = $db-&gt;has_sequence( $name )
+
  $db-&gt;rollback()
Return true if a sequence of the given name exists in the database.
+
Rollback the partially completed transaction.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 334: Line 416:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_sequence -->
+
<!-- Pod2Wiki=item_type_info -->
===create_sequence===
+
====type_info====
  
  $success = $db-&gt;create_sequence( $seq_name )
+
  $type_info = $db-&gt;type_info( $data_type )
Creates a new sequence object initialised to zero.
+
See {{API:PodLink|file=DBI|package_name=DBI|section=type_info|text=DBI/type_info}}.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 347: Line 429:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_sequence -->
+
<!-- Pod2Wiki=item_get_column_type -->
===drop_sequence===
+
====get_column_type====
 +
 
 +
$real_type = $db-&gt;get_column_type( $name, $data_type, $not_null, [ $length, $scale, %opts ] )
 +
Returns a SQL column definition for <tt>$name</tt> of type <tt>$type</tt>, usually something like:
 +
 
 +
  $name $type($length,$scale) [ NOT NULL ]
 +
 
 +
If <tt>$not_null</tt> is <tt>true</tt> column will be set to <tt>NOT NULL</tt>.
 +
 
 +
<tt>$length</tt> and <tt>$scale</tt> control the maximum lengths of character or decimal types (see below).
 +
 
 +
Other options available to refine the column definition:
 +
 
 +
  langid - character set/collation to use
 +
  sorted - whether this column will be used to order by
 +
 
 +
'''langid''' is mapped to real database values by the "dblanguages" configuration option. The database may not be able to order the request column type in which case, if <tt>sorted</tt> is true, the database may use a substitute column type.
 +
 
 +
<tt>$data_type</tt> is the SQL type. The types are constants defined by this module, to import them use:
 +
 
 +
  use EPrints::Database qw( :sql_types );
 +
 
 +
Supported types (n = requires <tt>$length</tt> argument):
 +
 
 +
Character data: <tt>SQL_VARCHAR(n)</tt>, <tt>SQL_LONGVARCHAR</tt>, <tt>SQL_CLOB</tt>.
 +
 
 +
Binary data: <tt>SQL_VARBINARY(n)</tt>, <tt>SQL_LONGVARBINARY</tt>.
 +
 
 +
Integer data: <tt>SQL_TINYINT</tt>, <tt>SQL_SMALLINT</tt>, <tt>SQL_INTEGER</tt>, <tt>SQL_BIGINT</tt>.
 +
 
 +
Floating-point data: <tt>SQL_REAL</tt>, <tt>SQL_DOUBLE</tt>.
  
$success = $db-&gt;drop_sequence( $seq_name )
+
Time data: <tt>SQL_DATE</tt>, <tt>SQL_TIME</tt>.
Deletes a sequence object.
+
 
 +
The actual column types used will be database-specific.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 360: Line 473:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_column -->
+
<!-- Pod2Wiki=head_basic_sql_operations -->
===drop_column===
+
===Basic SQL Operations===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_do -->
 +
====do====
  
  $success = $db-&gt;drop_column( $table, $column )
+
  $success = $db-&gt;do( $sql )
Drops a column from a table.
+
Execute the given <tt>$sql</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 373: Line 495:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_primary_key -->
+
<!-- Pod2Wiki=item_prepare -->
===get_primary_key===
+
====prepare====
  
  @columns = $db-&gt;get_primary_key( $tablename )
+
  $sth = $db-&gt;prepare( $sql )
Returns the list of column names that comprise the primary key for $tablename.
+
Prepare the given <tt>$sql</tt> and return a handle on it.
  
Returns empty list if no primary key exists.
+
Use the <tt>execute</tt> method on the returned {{API:PodLink|file=DBI|package_name=DBI|section=|text=DBI}} handle to execute the SQL:
  
 +
  my $sth = $db-&gt;prepare_select( "SELECT 'Hello, World'" );
 +
  $sth-&gt;execute;
 +
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 388: Line 513:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_index -->
+
<!-- Pod2Wiki=item_prepare_select -->
===create_index===
+
====prepare_select====
 +
 
 +
$sth = $db-&gt;prepare_select( $sql, [ %options ] )
 +
Prepare a <tt>SELECT</tt> statement <tt>$sql</tt> and return a handle to it. After  preparing a statement use <tt>execute()</tt> to execute it.
 +
 
 +
Returns a {{API:PodLink|file=DBI|package_name=DBI|section=|text=DBI}} statement handle.
 +
 
 +
The <tt>LIMIT</tt> SQL keyword is not universally supported, to specify this  use the <tt>limit</tt> option.
  
$success = $db-&gt;create_index( $tablename, @columns )
+
Options:
Creates an index over @columns for $tablename. Returns true on success.
 
  
 +
  limit - limit the number of rows returned
 +
  offset - return '''limit''' number of rows after offset
 +
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 401: Line 535:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_unique_index -->
+
<!-- Pod2Wiki=item_execute -->
===create_unique_index===
+
====execute====
  
  $success = $db-&gt;create_unique_index( $tablename, @columns )
+
  $success = $db-&gt;execute( $sth, $sql )
Creates a unique index over @columns for $tablename. Returns true on success.
+
Execute the SQL prepared earlier in the <tt>$sth</tt>. <tt>$sql</tt> is only  required for debugging purposes.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 414: Line 548:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item__update -->
+
<!-- Pod2Wiki=item_update -->
===_update===
+
====update====
  
  $success = $db-&gt;_update( $tablename, $keycols, $keyvals, $columns, @values )
+
  $success = $db-&gt;update( $dataset, $data, $changed )
UPDATES $tablename where $keycols equals $keyvals.
+
Updates a <tt>EPrints::DataObj</tt> from <tt>$dataset</tt> with the given <tt>$data</tt>.  The primary key field (e.g. <tt>eprintid</tt>) value must be included.
  
This method is internal.
+
Updates the <tt>ordervalues</tt> if the <tt>$dataset</tt> is {{API:PodLink|file=EPrints/DataSet#ordered|package_name=EPrints::DataSet#ordered|section=|text=ordered}}.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 429: Line 563:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item__update_quoted -->
+
<!-- Pod2Wiki=item__update -->
===_update_quoted===
+
====_update====
  
  $success = $db-&gt;_update_quoted( $tablename, $keycols, $keyvals, $columns, @qvalues )
+
  $rows = $db-&gt;_update( $tablename, $keycols, $keyvals, $columns, @values )
UPDATES $tablename where $keycols equals $keyvals. Won't quote $keyvals or @qvalues before use - use this method with care!
+
Updates <tt>$columns</tt> in <tt>$tablename</tt> with <tt>@values</tt> where <tt>$keycols</tt>  equals <tt>$keyvals</tt> and returns the number of rows affected.
  
This method is internal.
+
N.B. If no rows are affected, the result is still <tt>true</tt>,  see {{API:PodLink|file=DBI|package_name=DBI|section=|text=DBI}}'s <tt>execute()</tt> method.
 +
 
 +
This is an internal method.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 445: Line 581:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_insert -->
 
<!-- Pod2Wiki=item_insert -->
===insert===
+
====insert====
  
 
  $success = $db-&gt;insert( $table, $columns, @values )
 
  $success = $db-&gt;insert( $table, $columns, @values )
Inserts values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @values is a list of arrays containing values to insert.
+
Inserts <tt>@values</tt> into the table <tt>$table</tt>. If <tt>$columns</tt> is defined it will be used as a list of columns to insert into. <tt>@values</tt> is a list of arrays containing values to insert. These will be quoted before insertion.
 
 
Values will be quoted before insertion.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 460: Line 594:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_insert_quoted -->
 
<!-- Pod2Wiki=item_insert_quoted -->
===insert_quoted===
+
====insert_quoted====
  
 
  $success = $db-&gt;insert_quoted( $table, $columns, @qvalues )
 
  $success = $db-&gt;insert_quoted( $table, $columns, @qvalues )
Inserts values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @qvalues is a list of arrays containing values to insert.
+
Inserts values into the table <tt>$table</tt>. If <tt>$columns</tt> is defined it will be used as a list of columns to insert into. <tt>@qvalues</tt> is a list of arrays containing values to insert. These will NOT be quoted before insertion - care must be exercised!
 
 
Values will NOT be quoted before insertion - care must be exercised!
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 475: Line 607:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_delete_from -->
 
<!-- Pod2Wiki=item_delete_from -->
===delete_from===
+
====delete_from====
  
 
  $success = $db-&gt;delete_from( $table, $columns, @values )
 
  $success = $db-&gt;delete_from( $table, $columns, @values )
Perform a SQL DELETE FROM $table using $columns to build a where clause. @values is a list of array references of values in the same order as $columns.
+
Perform a SQL <tt>DELETE FROM</tt> <tt>$table</tt> using <tt>$columns</tt> to build a where clause. <tt>@values</tt> is a list of array references of values in the same order as <tt>$columns</tt>.
  
If you want to clear a table completely use clear_table().
+
If you want to clear a table completely use <tt>clear_table()</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 489: Line 621:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_add_record -->
+
<!-- Pod2Wiki=item_count_table -->
===add_record===
+
====count_table====
 +
 
 +
$n = $db-&gt;count_table( $tablename )
 +
Return the number of rows in the specified SQL table with  <tt>$tablename</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_clear_table -->
 +
====clear_table====
 +
 
 +
$db-&gt;clear_table( $tablename )
 +
Clears all records from the given table with <tt>$tablename</tt>. Use with  caution!
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$success = $db-&gt;add_record( $dataset, $data )
 
Add the given data as a new record in the given dataset. $data is a reference to a hash containing values structured for a record in the that dataset.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_quoting -->
 +
===Quoting===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 503: Line 657:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prep_int -->
 
<!-- Pod2Wiki=item_prep_int -->
===prep_int===
+
====prep_int====
  
 
  $mungedvalue = EPrints::Database::prep_int( $value )
 
  $mungedvalue = EPrints::Database::prep_int( $value )
Escape a numerical value for SQL. undef becomes NULL. Anything else becomes a number (zero if needed).
+
Escape numerical <tt>$value</tt> for an SQL statement. <tt>undef</tt> becomes <tt>NULL</tt>. Anything else becomes a number (zero if needed).
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 516: Line 670:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prep_value -->
 
<!-- Pod2Wiki=item_prep_value -->
===prep_value===
+
====prep_value====
  
 
  $mungedvalue = EPrints::Database::prep_value( $value )
 
  $mungedvalue = EPrints::Database::prep_value( $value )
Escape a value for SQL. Modify value such that " becomes \" and \ becomes \\ and ' becomes \'
+
Escape <tt>$value</tt> for an SQL statement. Modify value such that <tt>"</tt>  becomes <tt>\"</tt> and <tt>\</tt> becomes <tt>\\</tt> and <tt>'</tt> becomes <tt>\'</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 529: Line 683:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prep_like_value -->
 
<!-- Pod2Wiki=item_prep_like_value -->
===prep_like_value===
+
====prep_like_value====
  
 
  $mungedvalue = EPrints::Database::prep_like_value( $value )
 
  $mungedvalue = EPrints::Database::prep_like_value( $value )
Escape an value for an SQL like field. In addition to ' " and \ also escapes % and _
+
Escape <tt>$value</tt> for an SQL <tt>LIKE</tt> clause. In addition to <tt>'</tt> <tt>"</tt>  and <tt>\</tt> also escapes <tt>%</tt> and <tt>_</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 542: Line 696:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_quote_value -->
 
<!-- Pod2Wiki=item_quote_value -->
===quote_value===
+
====quote_value====
  
 
  $str = $db-&gt;quote_value( $value )
 
  $str = $db-&gt;quote_value( $value )
Return a quoted value. To quote a 'like' value you should do:
+
Return a quoted version of <tt>$value</tt>. To quote a <tt>LIKE</tt> value you should use:
  
  my $str = $database-&gt;quote_value( EPrints::Database::prep_like_value( $foo ) . '%' );
+
  $db-&gt;quote_value( EPrints::Database::prep_like_value( $foo ) . '%' );
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 557: Line 711:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_quote_int -->
 
<!-- Pod2Wiki=item_quote_int -->
===quote_int===
+
====quote_int====
  
 
  $str = $db-&gt;quote_int( $value )
 
  $str = $db-&gt;quote_int( $value )
Return a quoted integer value
+
Return a quoted integer for <tt>$value</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 570: Line 724:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_quote_binary -->
 
<!-- Pod2Wiki=item_quote_binary -->
===quote_binary===
+
====quote_binary====
  
 
  $str = $db-&gt;quote_binary( $bytes )
 
  $str = $db-&gt;quote_binary( $bytes )
Some databases (Oracle/PostgreSQL) require transforms of binary data to work correctly.
+
Some databases (Oracle/PostgreSQL) require transforms of binary data to work correctly.
  
This method should be called on data containing nul bytes or back-slashes before being passed on {{API:PodLink|file=|package_name=|section=quote_value|text=/quote_value}}.
+
This method should be called on data <tt>$bytes</tt> containing null bytes or back-slashes before being passed on [[API:EPrints/Database#quote_value|quote_value]].
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 585: Line 739:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_quote_ordervalue -->
 
<!-- Pod2Wiki=item_quote_ordervalue -->
===quote_ordervalue===
+
====quote_ordervalue====
  
 
  $str = $db-&gt;quote_ordervalue( $field, $value )
 
  $str = $db-&gt;quote_ordervalue( $field, $value )
Some databases (Oracle) can't order by CLOBS so need special treatment when creating the ordervalues tables. This method allows any fixing-up required for string data before it's inserted.
+
Some databases (Oracle) can't order by <tt>CLOB</tt>s so need special treatment when creating the ordervalues tables. This method allows any fixing-up required for string data <tt>$value</tt> for <tt>$field</tt> before it's inserted.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 598: Line 752:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_quote_identifier -->
 
<!-- Pod2Wiki=item_quote_identifier -->
===quote_identifier===
+
====quote_identifier====
  
 
  $str = $db-&gt;quote_identifier( @parts )
 
  $str = $db-&gt;quote_identifier( @parts )
Quote a database identifier (e.g. table names). Multiple @parts will be joined by dot.
+
Quote a database identifier (e.g. table names). Multiple <tt>@parts</tt>  will be joined by dots (<tt>.</tt>).
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 610: Line 764:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_update -->
+
<!-- Pod2Wiki=item_prepare_regexp -->
===update===
+
====prepare_regexp====
  
  $success = $db-&gt;update( $dataset, $data, $changed, $insert )
+
  $sql = $db-&gt;prepare_regexp( $col, $value )
Updates a record in the database with the given $data. Obviously the value of the primary key must be set.
+
The syntax used for regular expressions varies across databases. This  method takes two quoted string and returns a SQL expression that will  apply the quoted regexp <tt>$value</tt> to the quoted column <tt>$col</tt>.
 
 
This also updates the text indexes and the ordering keys.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 625: Line 777:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_remove -->
+
<!-- Pod2Wiki=item_sql_as -->
===remove===
+
====sql_as====
  
  $success = $db-&gt;remove( $dataset, $id )
+
  $sql = $db-&gt;sql_AS()
Attempts to remove the record with the primary key $id from the specified dataset.
+
Returns the syntactic glue to use when aliasing. SQL 92 databases will happily use <tt>AS</tt> but some databases (Oracle) will not accept it.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 638: Line 790:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_counters -->
+
<!-- Pod2Wiki=item_sql_like -->
===create_counters===
+
====sql_like====
 +
 
 +
$sql = $db-&gt;sql_LIKE()
 +
Returns the syntactic glue to use when making a case-insensitive  <tt>LIKE</tt>. PostgreSQL requires <tt>ILIKE</tt> while everything else uses  <tt>LIKE</tt> and the column collation.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$success = $db-&gt;create_counters
 
Create the counters used to store the highest current id of eprints, users etc.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_counters -->
 +
===Counters===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 651: Line 812:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_has_counter -->
+
<!-- Pod2Wiki=item_counter_current -->
===has_counter===
+
====counter_current====
  
  $success = $db-&gt;has_counter( $counter )
+
  $n = $db-&gt;counter_current( $counter )
Returns true if $counter exists.
+
Return the value of the previous counter_next on <tt>$counter</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 664: Line 825:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_counter -->
+
<!-- Pod2Wiki=item_counter_next -->
===create_counter===
+
====counter_next====
  
  $success = $db-&gt;create_counter( $name )
+
  $n = $db-&gt;counter_next( $counter )
Create and initialise to zero a new counter called $name.
+
Return the next unused value for the named <tt>$counter</tt>. Returns  <tt>undef</tt> if the <tt>$counter</tt> doesn't exist.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 677: Line 838:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_remove_counters -->
+
<!-- Pod2Wiki=item_counter_minimum -->
===remove_counters===
+
====counter_minimum====
  
  $success = $db-&gt;remove_counters
+
  $db-&gt;counter_minimum( $counter, $value )
Destroy all counters.
+
Ensure that the <tt>$counter</tt> is set no lower than <tt>$value</tt>. This is  used when importing eprints which may not be in scrict sequence.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 690: Line 851:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_counter -->
+
<!-- Pod2Wiki=item_counter_reset -->
===drop_counter===
+
====counter_reset====
  
  $success = $db-&gt;drop_counter( $name )
+
  $db-&gt;counter_reset( $counter )
Destroy the counter named $name.
+
Reset the <tt>$counter</tt>. Use with caution.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 704: Line 865:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_next_doc_pos -->
 
<!-- Pod2Wiki=item_next_doc_pos -->
===next_doc_pos===
+
====next_doc_pos====
  
 
  $n = $db-&gt;next_doc_pos( $eprintid )
 
  $n = $db-&gt;next_doc_pos( $eprintid )
Return the next unused document pos for the given eprintid.
+
Return the next unused document position for the given <tt>$eprintid</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 716: Line 877:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_counter_current -->
+
<!-- Pod2Wiki=head_dataset_data -->
===counter_current===
+
===Dataset Data===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_exists -->
 +
====exists====
  
  $n = $db-&gt;counter_current( $counter )
+
  $boolean = $db-&gt;exists( $dataset, $id )
Return the value of the previous counter_next on $counter.
+
Return <tt>true</tt> if there exists an [[API:EPrints/DataObj|EPrints::DataObj]] from the <tt>$dataset</tt> with its primary key set to <tt>$id</tt>. Otherwise, return  <tt>false</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 729: Line 899:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_counter_next -->
+
<!-- Pod2Wiki=item_add_record -->
===counter_next===
+
====add_record====
  
  $n = $db-&gt;counter_next( $counter )
+
  $success = $db-&gt;add_record( $dataset, $data )
Return the next unused value for the named counter. Returns undef if the counter doesn't exist.
+
Add the given <tt>$data</tt> as a new record in the given <tt>$dataset</tt><tt>$data</tt> is a reference to a hash containing values structured for a  record in the that <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 742: Line 912:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_counter_minimum -->
+
<!-- Pod2Wiki=item_remove -->
===counter_minimum===
+
====remove====
  
  $db-&gt;counter_minimum( $counter, $value )
+
  $success = $db-&gt;remove( $dataset, $id )
Ensure that the counter is set no lower than $value. This is used when importing eprints which may not be in scrict sequence.
+
Attempts to remove the [[API:EPrints/DataObj|EPrints::DataObj]] with the primary key <tt>$id</tt>  from the specified <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 755: Line 925:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_counter_reset -->
+
<!-- Pod2Wiki=head_searching_caching_and_object_retrieval -->
===counter_reset===
+
===Searching, caching and object retrieval===
 
 
$db-&gt;counter_reset( $counter )
 
Reset the counter. Use with caution.
 
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 769: Line 935:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_cache_exp -->
 
<!-- Pod2Wiki=item_cache_exp -->
===cache_exp===
+
====cache_exp====
  
 
  $searchexp = $db-&gt;cache_exp( $cacheid )
 
  $searchexp = $db-&gt;cache_exp( $cacheid )
Return the serialised Search of a the cached search with id $cacheid. Return undef if the id is invalid or expired.
+
Return the serialised search of a the cached search with <tt>$cacheid</tt>. Return <tt>undef</tt> if the <tt>$cacheid</tt> is invalid or expired.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 782: Line 948:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_cache -->
 
<!-- Pod2Wiki=item_cache -->
===cache===
+
====cache====
  
 
  $cacheid = $db-&gt;cache( $searchexp, $dataset, $srctable, [$order], [$list] )
 
  $cacheid = $db-&gt;cache( $searchexp, $dataset, $srctable, [$order], [$list] )
Create a cache of the specified search expression from the SQL table $srctable.
+
Create a cache of the specified search expression from the SQL table <tt>$srctable</tt>.
  
If $order is set then the cache is ordered by the specified fields. For example "-year/title" orders by year (descending). Records with the same year are ordered by title.
+
If <tt>$order</tt> is set then the cache is ordered by the specified fields. For example <tt>-year/title</tt> orders by year (descending). Records with the same year are ordered by title.
  
If $srctable is set to "LIST" then order is ignored and the list of ids is taken from the array reference $list.
+
If <tt>$srctable</tt> is set to <tt>LIST</tt> then order is ignored and the list of IDs is taken from the array reference <tt>$list</tt>.
  
If $srctable is set to "ALL" every matching record from $dataset is added to the cache, optionally ordered by $order.
+
If <tt>$srctable</tt> is set to <tt>ALL</tt> every matching record from $dataset is added to the cache, optionally ordered by <tt>$order</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 801: Line 967:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_cache_table -->
 
<!-- Pod2Wiki=item_cache_table -->
===cache_table===
+
====cache_table====
  
 
  $tablename = $db-&gt;cache_table( $id )
 
  $tablename = $db-&gt;cache_table( $id )
Return the SQL table used to store the cache with id $id.
+
Return the name of the SQL table used to store the cache with <tt>$id</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 813: Line 979:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_index_ids -->
+
<!-- Pod2Wiki=item_cache_userid -->
===get_index_ids===
+
====cache_userid====
  
  $ids = $db-&gt;get_index_ids( $table, $condition )
+
  $userid = $db-&gt;cache_userid( $id )
Return a reference to an array of the distinct primary keys from the given SQL table which match the specified condition.
+
Returns the <tt>userid</tt> associated with the cache with <tt>$id</tt> if that  cache exists.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 826: Line 992:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_search -->
+
<!-- Pod2Wiki=item_get_cachemap -->
===search===
+
====get_cachemap====
 
 
$ids = $db-&gt;search( $keyfield, $tables, $conditions, [$main_table_alias] )
 
Return a reference to an array of ids - the results of the search specified by $conditions accross the tables specified in the $tables hash where keys are tables aliases and values are table names.
 
  
If no table alias is passed then M is assumed.  
+
$cachemap = $db-&gt;get_cachemap( $id )
 +
Return the cachemap with $&lt;id&gt;.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 841: Line 1,005:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_cache -->
+
<!-- Pod2Wiki=item_search -->
===drop_cache===
+
====search====
 +
 
 +
$ids = $db-&gt;search( $keyfield, $tables, $conditions, [ $main_table_alias ] )
 +
Return a reference to an array of <tt>$keyfield</tt> IDs - the results of  the search specified by <tt>$conditions</tt> across the tables specified in  the <tt>$tables</tt> hash where keys are tables aliases and values are table  names.
  
$db-&gt;drop_cache( $id )
+
If no <tt>$main_table_alias</tt> is specified then <tt>M</tt> is assumed.  
Remove the cached search with the given id.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 854: Line 1,020:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_count_table -->
+
<!-- Pod2Wiki=item_drop_cache -->
===count_table===
+
====drop_cache====
  
  $n = $db-&gt;count_table( $tablename )
+
  $db-&gt;drop_cache( $id )
Return the number of rows in the specified SQL table.
+
Remove the cached search with the given <tt>$id</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 868: Line 1,034:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_from_cache -->
 
<!-- Pod2Wiki=item_from_cache -->
===from_cache===
+
====from_cache====
  
  $foo = $db-&gt;from_cache( $dataset, $cacheid, [$offset], [$count], [$justids] )
+
  $items = $db-&gt;from_cache( $dataset, $cacheid, [ $offset, $count, $justids ] )
Return a reference to an array containing all the items from the given dataset that have id's in the specified cache. The cache may be specified either by id or serialised search expression.  
+
Return a reference to an array containing all the items from the given <tt>$dataset</tt> that have IDs in the cache specified by <tt>$cacheid</tt>. The cache may be specified either by ID or serialised search expression.  
  
$offset is an offset from the start of the cache and $count is the number of records to return.
+
<tt>$offset</tt> is an offset from the start of the cache and <tt>$count</tt> is the number of records to return.
  
If $justids is true then it returns just an ref to an array of the record ids, not the objects.
+
If <tt>$justids</tt> is <tt>true</tt> then it returns just a reference to an array of the record IDs and not the objects themselves.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 885: Line 1,051:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_drop_orphan_cache_tables -->
 
<!-- Pod2Wiki=item_drop_orphan_cache_tables -->
===drop_orphan_cache_tables===
+
====drop_orphan_cache_tables====
  
 
  $c = $db-&gt;drop_orphan_cache_tables
 
  $c = $db-&gt;drop_orphan_cache_tables
Drop tables called "cacheXXX" where XXX is an integer. Returns the number of tables dropped.
+
Drop tables called <tt>cacheXXX</tt> where <tt>XXX</tt> is an integer. Returns the number of cache tables dropped.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 898: Line 1,064:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_single -->
 
<!-- Pod2Wiki=item_get_single -->
===get_single===
+
====get_single====
  
 
  $obj = $db-&gt;get_single( $dataset, $id )
 
  $obj = $db-&gt;get_single( $dataset, $id )
Return a single item from the given dataset. The one with the specified id.
+
Return a single &lt;EPrints::DataObj&gt; from the given <tt>$dataset</tt> with primary key set to <tt>$id</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 911: Line 1,077:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_all -->
 
<!-- Pod2Wiki=item_get_all -->
===get_all===
+
====get_all====
  
 
  $items = $db-&gt;get_all( $dataset )
 
  $items = $db-&gt;get_all( $dataset )
Returns a reference to an array with all the items from the given dataset.
+
Returns a reference to an array with all the &lt;EPrints::DataObj&gt;s from the given <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 924: Line 1,090:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_cache_ids -->
 
<!-- Pod2Wiki=item_get_cache_ids -->
===get_cache_ids===
+
====get_cache_ids====
  
 
  @ids = $db-&gt;get_cache_ids( $dataset, $cachemap, $offset, $count )
 
  @ids = $db-&gt;get_cache_ids( $dataset, $cachemap, $offset, $count )
Returns a list of $count ids from $cache_id starting at $offset and in the order in the cachemap.
+
Returns a list of <tt>$count</tt> IDs from <tt>$cache_id</tt> starting at <tt>$offset</tt> and in the order in the <tt>$cachemap</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 937: Line 1,103:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_dataobjs -->
 
<!-- Pod2Wiki=item_get_dataobjs -->
===get_dataobjs===
+
====get_dataobjs====
  
  @dataobjs = $db-&gt;get_dataobjs( $dataset [, $id [, $id ] ] )
+
  @dataobjs = $db-&gt;get_dataobjs( $dataset, [ $id, $id, ... ] )
Retrieves the records in $dataset with the given $id(s). If an $id doesn't exist in the database it will be ignored.
+
Retrieves the records in <tt>$dataset</tt> with the given <tt>$id</tt>(s). If an <tt>$id</tt> doesn't exist in the database it will be ignored.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 950: Line 1,116:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_values -->
 
<!-- Pod2Wiki=item_get_values -->
===get_values===
+
====get_values====
  
  $foo = $db-&gt;get_values( $field, $dataset )
+
  $values = $db-&gt;get_values( $field, $dataset )
Return a reference to an array of all the distinct values of the  EPrints::MetaField specified.
+
Return a reference to an array of all the distinct values of the  [[API:EPrints/MetaField|EPrints::MetaField]] <tt>$field</tt> for the <tt>$dataset</tt> specified.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 963: Line 1,129:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_sort_values -->
 
<!-- Pod2Wiki=item_sort_values -->
===sort_values===
+
====sort_values====
 
 
$values = $db-&gt;sort_values( $field, $values [, $langid ] )
 
ALPHA!!! Liable to API change!!!
 
  
Sorts and returns the list of $values using the database.
+
$values = $db-&gt;sort_values( $field, $values, [ $langid ] )
 +
Sorts and returns the list of <tt>$values</tt> using the database.
  
$field is used to get the order value for each value. $langid (or $session-&gt;get_langid if unset) is used to determine the database collation to use when sorting the resulting order values.
+
<tt>$field</tt> is used to get the order value for each value. <tt>$langid</tt>  (or $session-&gt;get_langid if unset) is used to determine the database collation to use when sorting the resulting order values.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 980: Line 1,144:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_ids_by_field_values -->
 
<!-- Pod2Wiki=item_get_ids_by_field_values -->
===get_ids_by_field_values===
+
====get_ids_by_field_values====
  
  $ids = $db-&gt;get_ids_by_field_values( $field, $dataset [ %opts ] )
+
  $ids = $db-&gt;get_ids_by_field_values( $field, $dataset, [ %opts ] )
Return a reference to a hash table where the keys are field value ids and the value is a reference to an array of ids.
+
Return a reference to a hash table where the keys are specified  <tt>$datasets</tt>'s <tt>$field</tt> value IDs and the values are references to arrays of IDs.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 992: Line 1,156:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_do -->
+
<!-- Pod2Wiki=item_dequeue_events -->
===do===
+
====dequeue_events====
  
  $success = $db-&gt;do( $sql )
+
  @events = $db-&gt;dequeue_events( $n )
Execute the given SQL.
+
Attempt to dequeue upto <tt>$n</tt> events. May return between <tt>0</tt> and  <tt>$n</tt> events depending on parallel processes and how many events are  remaining in the queue.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,005: Line 1,169:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_prepare -->
+
<!-- Pod2Wiki=item_ci_lookup -->
===prepare===
+
====ci_lookup====
 +
 
 +
$value = $db-&gt;ci_lookup( $field, $value )
 +
This is a hacky method to support case-insensitive lookup for usernames, emails, etc.  It returns the actual case-sensitive version of <tt>$value</tt> if there is a case-insensitive match for the <tt>$field</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$sth = $db-&gt;prepare( $sql )
 
Prepare the given $sql and return a handle on it.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_password_validation_and_secret_fields -->
 +
===Password Validation and Secret Fields===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 1,018: Line 1,191:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_prepare_select -->
+
<!-- Pod2Wiki=item_valid_login -->
===prepare_select===
+
====valid_login====
 +
 
 +
$db-&gt;valid_login( $username, $password )
 +
Returns whether the clear-text <tt>$password</tt> matches the stored crypted  password for the <tt>$username</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$sth = $db-&gt;prepare_select( $sql [, %options ] )
 
Prepare a SELECT statement $sql and return a handle to it. After preparing a statement use execute() to execute it.
 
  
The LIMIT SQL keyword is not universally supported, to specify a LIMIT you must use the '''limit''' option.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_secret_matches -->
 +
====secret_matches====
  
Options:
+
$db-&gt;secret_matches( $dataobj, $fieldname, $token [, $callback ] )
 +
Returns whether the clear-text <tt>$token</tt> matches the stored crypted  field with <tt>$fieldname</tt> for the <tt>$dataobj</tt> according to the  <tt>$callback</tt> function.
 +
 
 +
If not set, <tt>$callback</tt> defaults to [[API:EPrints/Utils#crypt_equals|EPrints::Utils#crypt_equals]].
  
  limit - limit the number of rows returned
 
  offset - return '''limit''' number of rows after offset
 
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 1,038: Line 1,219:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_execute -->
+
<!-- Pod2Wiki=item_is_secret_set -->
===execute===
+
====is_secret_set====
  
  $success = $db-&gt;execute( $sth, $sql )
+
  $boolean = $db-&gt;is_secret_set( $dataobj, $fieldname )
Execute the SQL prepared earlier. $sql is only passed in for debugging purposes.
+
Returns a boolean for whether the secret <tt>$fieldname</tt> for <tt>$dataobj</tt>  has a value set.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,051: Line 1,232:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_has_dataset -->
+
<!-- Pod2Wiki=head_database_schema_manipulation -->
===has_dataset===
+
===Database Schema Manipulation===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_has_sequence -->
 +
====has_sequence====
 +
 
 +
$boolean = $db-&gt;has_sequence( $name )
 +
Returns <tt>true</tt> if a sequence of the given <tt>$name</tt> exists in the  database. Otherwise, returns <tt>false</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
  
$db-&gt;has_dataset( $dataset )
+
<!-- Pod2Wiki= -->
Returns true if $dataset exists in the database or has no database tables.
+
</div>
 +
<!-- Pod2Wiki=item_create_sequence -->
 +
====create_sequence====
  
This does not check that all fields are configured - see has_field().
+
$success = $db-&gt;create_sequence( $name )
 +
Creates a new sequence object with <tt>$name</tt> and initialises to zero.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,066: Line 1,267:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_has_field -->
+
<!-- Pod2Wiki=item_drop_sequence -->
===has_field===
+
====drop_sequence====
  
  $db-&gt;has_field( $dataset, $field )
+
  $success = $db-&gt;drop_sequence( $name )
Returns true if $field is in the database for $dataset.
+
Deletes a sequence object with <tt>$name</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,079: Line 1,280:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_add_field -->
+
<!-- Pod2Wiki=item_has_column -->
===add_field===
+
====has_column====
 +
 
 +
$boolean = $db-&gt;has_column( $table, $column )
 +
Return <tt>true</tt> if the named <tt>$table</tt> has the named <tt>$column</tt> in the  database.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
  
$db-&gt;add_field( $dataset, $field [, $force ] )
+
<!-- Pod2Wiki= -->
Add $field to $dataset's tables.
+
</div>
 +
<!-- Pod2Wiki=item_drop_column -->
 +
====drop_column====
  
If $force is true will modify/replace an existing column (use with care!).
+
$success = $db-&gt;drop_column( $table, $column )
 +
Drops the named <tt>$column</tt> from the named <tt>$table</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,094: Line 1,306:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_remove_field -->
+
<!-- Pod2Wiki=item_get_primary_key -->
===remove_field===
+
====get_primary_key====
 +
 
 +
@columns = $db-&gt;get_primary_key( $tablename )
 +
Returns a list of column names that comprise the primary key for  the <tt>$tablename</tt>.
  
$db-&gt;remove_field( $dataset, $field )
+
Returns an empty list if no primary key exists.
Remove $field from $dataset's tables.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,107: Line 1,321:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_rename_field -->
+
<!-- Pod2Wiki=item_index_name -->
===rename_field===
+
====index_name====
  
  $ok = $db-&gt;rename_field( $dataset, $field, $old_name )
+
  $name = $db-&gt;index_name( $table, @cols )
Rename a $field in the database from it's old name $old_name.
+
Returns the name of the first index that starts with named columns  <tt>@cols</tt> in the named <tt>$table</tt>.
  
Returns true if the field was successfully renamed.
+
Returns <tt>undef</tt> if no index exists.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,122: Line 1,336:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_exists -->
+
<!-- Pod2Wiki=item_get_index_ids -->
===exists===
+
====get_index_ids====
  
  $boolean = $db-&gt;exists( $dataset, $id )
+
  $ids = $db-&gt;get_index_ids( $table, $condition )
Return true if a record with the given primary key exists in the dataset, otherwise false.
+
Return a reference to an array of the distinct primary keys from the named SQL <tt>$table</tt> which match the specified <tt>$condition</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,135: Line 1,349:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_set_debug -->
+
<!-- Pod2Wiki=item_create_index -->
===set_debug===
+
====create_index====
  
  $db-&gt;set_debug( $boolean )
+
  $success = $db-&gt;create_index( $table, @columns )
Set the SQL debug mode to true or false.
+
Creates an index over <tt>@columns</tt> for named <tt>$table</tt>. Returns <tt>true</tt>  on success, <tt>false</tt> otherwise.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,148: Line 1,362:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_create_version_table -->
+
<!-- Pod2Wiki=item_create_unique_index -->
===create_version_table===
+
====create_unique_index====
  
  $db-&gt;create_version_table
+
  $success = $db-&gt;create_unique_index( $tablename, @columns )
Make the version table (and set the only value to be the current version of eprints).
+
Creates a unique index over <tt>@columns</tt> for named <tt>$table</tt>. Returns  <tt>true</tt> on success, <tt>false</tt> otherwise.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,161: Line 1,375:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_version_table -->
+
<!-- Pod2Wiki=item_create_foreign_key -->
===drop_version_table===
+
====create_foreign_key====
 +
 
 +
$ok = $db-&gt;create_foreign_key( $main_table, $table, $key_field )
 +
Create a foreign key relationship between named <tt>$main_table</tt> and  named <tt>$table</tt> using <tt>$key_field</tt>.
  
  $db-&gt;drop_version_table
+
This will cause records in <tt>$table</tt> to be deleted if the equivalent record is deleted from <tt>$main_table</tt>.
Drop the version table.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,174: Line 1,390:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_set_version -->
+
<!-- Pod2Wiki=item_get_tables -->
===set_version===
+
====get_tables====
 +
 
 +
@tables = $db-&gt;get_tables( [ $dbname ] )
 +
Returns a list of all the tables in the database. 
  
$db-&gt;set_version( $versionid );
+
<tt>$dbname</tt> specifies a particular database name of current connection has access to more than one database.
Set the version id table in the SQL database to the given value (used by the upgrade script).
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,188: Line 1,406:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_has_table -->
 
<!-- Pod2Wiki=item_has_table -->
===has_table===
+
====has_table====
  
 
  $boolean = $db-&gt;has_table( $tablename )
 
  $boolean = $db-&gt;has_table( $tablename )
Return true if a table of the given name exists in the database.
+
Returns boolean dependent on whether a table of the <tt>$tablename</tt>  exists in the database.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create_table -->
 +
====create_table====
 +
 
 +
$success = $db-&gt;create_table( $tablename, $setkey, @fields );
 +
Creates a new table with <tt>$tablename</tt> based on <tt>@fields</tt>.
 +
 
 +
The first <tt>$setkey</tt> number of fields are used for its primary key.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,200: Line 1,433:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_has_column -->
+
<!-- Pod2Wiki=item_drop_table -->
===has_column===
+
====drop_table====
 +
 
 +
$db-&gt;drop_table( @tables )
 +
Delete the named <tt>@tables</tt>. Use with caution!
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_rename_table -->
 +
====rename_table====
 +
 
 +
$db-&gt;rename_table( $table_from, $table_to )
 +
Renames the table named <tt>$table_from</tt> to <tt>$table_to</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_swap_table -->
 +
====swap_table====
 +
 
 +
$db-&gt;swap_table( $table_a, $table_b )
 +
Renames table named <tt>$table_a</tt> to <tt>$table_b</tt> and vice-versa.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_eprints_schema_manipulation -->
 +
===EPrints Schema Manipulation===
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create_archive_tables -->
 +
====create_archive_tables====
 +
 
 +
$success = $db-&gt;create_archive_tables()
 +
Create all the SQL tables for all datasets.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_drop_archive_tables -->
 +
====drop_archive_tables====
 +
 
 +
$db-&gt;drop_archive_tables()
 +
Destroy all tables used by EPrints in the database.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create_version_table -->
 +
====create_version_table====
 +
 
 +
$db-&gt;create_version_table
 +
Make the version table (and set the only value to be the current version of EPrints).
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_drop_version_table -->
 +
====drop_version_table====
  
  $boolean = $db-&gt;has_column( $tablename, $columnname )
+
  $db-&gt;drop_version_table
Return true if the a table of the given name has a column named $columnname in the database.
+
Drop the version table.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,213: Line 1,533:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_index_name -->
+
<!-- Pod2Wiki=item_has_dataset -->
===index_name===
+
====has_dataset====
  
  $name = $db-&gt;index_name( $table, @columns )
+
  $db-&gt;has_dataset( $dataset )
Returns the name of the first index that starts with @columns on the $table table.
+
Returns <tt>true</tt> if <tt>$dataset</tt> exists in the database and has all  expected tables including ordervalues and index tables.
  
Returns undef if no index exists.
+
This does not check that all fields are configured - see &lt;/has_field&gt;.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,228: Line 1,548:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_drop_table -->
+
<!-- Pod2Wiki=item_has_dataset_index_tables -->
===drop_table===
+
====has_dataset_index_tables====
  
  $db-&gt;drop_table( $tablename )
+
  $db-&gt;has_dataset_index_tables( $dataset )
Delete the named table. Use with caution!
+
Returns <tt>true</tt> if index tables for <tt>$dataset</tt> exists of if this is  not indexable.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,241: Line 1,561:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_clear_table -->
+
<!-- Pod2Wiki=item_create_dataset_tables -->
===clear_table===
+
====create_dataset_tables====
  
  $db-&gt;clear_table( $tablename )
+
  $success = $db-&gt;create_dataset_tables( $dataset )
Clears all records from the given table, use with caution!
+
Creates all the SQL tables for the specified <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,254: Line 1,574:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_rename_table -->
+
<!-- Pod2Wiki=item_drop_dataset_tables -->
===rename_table===
+
====drop_dataset_tables====
  
  $db-&gt;rename_table( $tablename, $newtablename )
+
  $db-&gt;drop_dataset_tables( $dataset )
Renames the table from the old name to the new one.
+
Drops all the SQL tables for the specified <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,267: Line 1,587:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_swap_table -->
+
<!-- Pod2Wiki=item_create_dataset_index_tables -->
===swap_table===
+
====create_dataset_index_tables====
  
  $db-&gt;swap_table( $table_a, $table_b )
+
  $success = $db-&gt;create_dataset_index_tables( $dataset )
Swap table a and table b.  
+
Creates all the index tables for the specified <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,280: Line 1,600:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_tables -->
+
<!-- Pod2Wiki=item_create_dataset_ordervalues_tables -->
===get_tables===
+
====create_dataset_ordervalues_tables====
  
  @tables = $db-&gt;get_tables
+
  $success = $db-&gt;create_dataset_ordervalues_tables( $dataset )
Return a list of all the tables in the database.
+
Creates all the ordervalues tables for the specified <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,293: Line 1,613:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_version -->
+
<!-- Pod2Wiki=item_has_field -->
===get_version===
+
====has_field====
  
  $version = $db-&gt;get_version
+
  $db-&gt;has_field( $dataset, $field )
Return the version of eprints which the database is compatable with or undef if unknown (before v2.1).
+
Returns <tt>true</tt> if <tt>$field</tt> is in the database for <tt>$dataset</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,306: Line 1,626:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_is_latest_version -->
+
<!-- Pod2Wiki=item_add_field -->
===is_latest_version===
+
====add_field====
 +
 
 +
$db-&gt;add_field( $dataset, $field, [ $force ] )
 +
Add <tt>$field</tt> to <tt>$dataset</tt>'s tables.
  
$boolean = $db-&gt;is_latest_version
+
If <tt>$force</tt> is <tt>true</tt> modify/replace an existing column. Use with  care!
Return true if the SQL tables are in the correct configuration for this edition of eprints. Otherwise false.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,319: Line 1,641:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_valid_login -->
+
<!-- Pod2Wiki=item_remove_field -->
===valid_login===
+
====remove_field====
  
  $db-&gt;valid_login( $username, $password )
+
  $db-&gt;remove_field( $dataset, $field )
Returns whether the clear-text $password matches the stored crypted password for $username.
+
Remove <tt>$field</tt> from <tt>$dataset</tt>'s tables.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,332: Line 1,654:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_server_version -->
+
<!-- Pod2Wiki=item_rename_field -->
===get_server_version===
+
====rename_field====
 +
 
 +
$ok = $db-&gt;rename_field( $dataset, $field, $old_name )
 +
Rename the <tt>$field</tt> in the <tt>$dataset</tt> from its <tt>$old_name</tt>.
  
$version = $db-&gt;get_server_version
+
Returns <tt>true</tt> if the <tt>$field</tt> is successfully renamed.
Return the database server version.
 
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,345: Line 1,669:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_default_charset -->
+
<!-- Pod2Wiki=item_create_counters -->
===get_default_charset===
+
====create_counters====
  
  $charset = $db-&gt;get_default_charset( LANGUAGE )
+
  $success = $db-&gt;create_counters
Return the character set to use for LANGUAGE.
+
Create the counters used to store the highest current ID of eprints, users, etc.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
Returns undef if character sets are unsupported.
+
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_has_counter -->
 +
====has_counter====
 +
 
 +
$success = $db-&gt;has_counter( $counter )
 +
Returns <tt>true</tt> if <tt>$counter</tt> exists.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,360: Line 1,695:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_default_collation -->
+
<!-- Pod2Wiki=item_create_counter -->
===get_default_collation===
+
====create_counter====
 +
 
 +
$success = $db-&gt;create_counter( $name )
 +
Create and initialise to zero a new counter with <tt>$name</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$collation = $db-&gt;get_default_collation( LANGUAGE )
 
Return the collation to use for LANGUAGE.
 
  
Returns undef if collation is unsupported.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_remove_counters -->
 +
====remove_counters====
 +
 
 +
$success = $db-&gt;remove_counters
 +
Destroy all counters.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,375: Line 1,721:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_get_driver_name -->
+
<!-- Pod2Wiki=item_drop_counter -->
===get_driver_name===
+
====drop_counter====
 +
 
 +
$success = $db-&gt;drop_counter( $name )
 +
Destroy the counter named <tt>$name</tt>.
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$driver = $db-&gt;get_driver_name
 
Return the database driver name.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_user_messages -->
 +
===User Messages===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 1,388: Line 1,743:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_dequeue_events -->
+
<!-- Pod2Wiki=item_save_user_message -->
===dequeue_events===
+
====save_user_message====
  
  @events = $db-&gt;dequeue_events( $n )
+
  $message = $db-&gt;save_user_message( $userid, $m_type, $dom_m_data )
Attempt to dequeue upto $n events. May return between 0 and $n events depending on parallel processes and how many events are remaining on the queue.
+
Save user message provided in XML DOM object <tt>$dom_m_data</tt> as a  sanitized string in a [[API:EPrints/DataObj/Message|EPrints::DataObj::Message]] using <tt>$m_type</tt> to define the message type and <tt>$userid</tt> for the ID of the user whose message it is.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,401: Line 1,756:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_prepare_regexp -->
+
<!-- Pod2Wiki=item_get_user_messages -->
===prepare_regexp===
+
====get_user_messages====
  
  $sql = $db-&gt;prepare_regexp( $quoted_column, $quoted_value )
+
  @messages = $db-&gt;get_user_messages( $userid, %opts )
The syntax used for regular expressions varies across databases. This method takes two '''quoted''' values and returns a SQL expression that will apply the regexp ($quoted_value) to the column ($quoted_column).
+
Get the messages for a user with ID <tt>$userid</tt> and clear messages if <tt>$opt{clear}</tt> is set.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,414: Line 1,769:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_sql_as -->
+
<!-- Pod2Wiki=item_clear_user_messages -->
===sql_as===
+
====clear_user_messages====
  
  $sql = $db-&gt;sql_AS()
+
  $db-&gt;clear_user_messages( $userid )
Returns the syntactic glue to use when aliasing. SQL 92 DBs will happilly use " AS " but some DBs (Oracle!) won't accept it.
+
Clear all messages for user with ID <tt>$userid</tt>.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 1,427: Line 1,782:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_sql_like -->
+
<!-- Pod2Wiki=head_see_also -->
===sql_like===
+
==SEE ALSO==
 +
To access database-stored objects use the methods provided by the  following modules: [[API:EPrints/Repository|EPrints::Repository]], [[API:EPrints/DataSet|EPrints::DataSet]].
 +
 
 +
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
  
$sql = $db-&gt;sql_LIKE()
 
Returns the syntactic glue to use when making a case-insensitive LIKE. PostgreSQL requires "ILIKE" while everything else uses "LIKE" and the column collation.
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
{{API:Copyright}}
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>

Latest revision as of 21:20, 4 March 2022

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


Contents

NAME

EPrints::Database - a connection to the SQL database for an eprints session.

User Comments


DESCRIPTION

EPrints Database Access Module

Provides access to the backend database. All database access done via this module, in the hope that the backend can be replaced as easily as possible.

In most use-cases it should not be necessary to use the database module directly. Instead you should use EPrints::DataSet or EPrints::MetaField accessor methods to access objects and field values respectively.

User Comments


Cross-database Support

Any use of SQL statements must use quote_identifier to quote database tables and columns and quote_value to quote values. The only exception to this are the EPrints::Database::* modules which provide database-driver specific extensions.

User Comments


Quoting SQL Values

By convention variables that contain already quoted values are prefixed with Q_ so they can be easily recognised when used in string interpolation:

my $Q_value = $db->quote_value( "Hello, World!" );
$db->do("SELECT $Q_value");
 

Where possible you should avoid quoting values yourself, instead use a method that accepts unquoted values which will (safely) do the work for you.

User Comments


CONSTANTS

All the SQL_ column types defined by Perl module DBI and the following:

User Comments


SQL_NULL

A column value is undefined.

User Comments


SQL_NOT_NULL

A column value is defined.

User Comments


INSTANCE VARIABLES

User Comments


$self->{session}

The EPrints::Session which is associated with this database connection.

User Comments


$self->{debug}

If true then SQL is logged.

User Comments


$self->{dbh}

The handle on the actual database connection.

User Comments


METHODS

User Comments


Database

User Comments


new

$db = EPrints::Database->new( $repo, [ %opts ] )

Create a connection to the database.

Options:

 db_connect - Boolean. Also connect to the database (default: true).

User Comments


create

$db = $db->create( $username, $password )

Create and connect to a new database using user account $username and $password.

User Comments


build_connection_string

$dbstr = EPrints::Database::build_connection_string( %params )

Build the string to use to connect to the database via DBI.

Parameters:

dbname - Database name (REQUIRED).
dbdriver - Database driver (e.g. mysql, Oracle, pgsql, default: mysql).
dbhost - Database host.  Assumes localhost if unset.
dbport - Port to connect to database host.  Assumes default for driver if unset.
dbsock - Socket file to connect to database through.

User Comments


connect

$db->connect()

Connects to the database.

User Comments


disconnect

$db->disconnect()

Disconnects from the EPrints database. Should always be done before any script exits.

User Comments


set_debug

$db->set_debug( $boolean )

Set the SQL debug mode to true or false.

User Comments


set_version

$db->set_version( $versionid );

Set the version id table in the SQL database to the given versionid (used by the upgrade script).

User Comments


get_version

$version = $db->get_version

Returns the current database schema version.

User Comments


is_latest_version

$boolean = $db->is_latest_version

Return true if the SQL tables are in the correct configuration for this edition of eprints. Otherwise, false.

User Comments


get_server_version

$version = $db->get_server_version

Return the database server version.

User Comments


get_default_charset

$charset = $db->get_default_charset

Return the character set to use.

Returns undef if character sets are unsupported.

User Comments


get_default_collation

$collation = $db->get_default_collation( $lang )

Return the collation to use for language $lang.

Returns undef if collation is unsupported.

User Comments


get_driver_name

$driver = $db->get_driver_name

Return the database driver name.

User Comments


error

$errstr = $db->error()

Return a string describing the last SQL error.

User Comments


retry_error

$boolean = $db->retry_error()

Returns a boolean for whether the database error is a retry error.

User Comments


duplicate_error

$boolean = $db->duplicate_error()

Returns a boolean for whether the database error is a duplicate error.

User Comments


begin

$db->begin()

Begin a transaction.

User Comments


commit

$db->commit()

Commit the previously begun transaction.

User Comments


rollback

$db->rollback()

Rollback the partially completed transaction.

User Comments


type_info

$type_info = $db->type_info( $data_type )

See DBI/type_info.

User Comments


get_column_type

$real_type = $db->get_column_type( $name, $data_type, $not_null, [ $length, $scale, %opts ] )

Returns a SQL column definition for $name of type $type, usually something like:

 $name $type($length,$scale) [ NOT NULL ]
 

If $not_null is true column will be set to NOT NULL.

$length and $scale control the maximum lengths of character or decimal types (see below).

Other options available to refine the column definition:

 langid - character set/collation to use
 sorted - whether this column will be used to order by
 

langid is mapped to real database values by the "dblanguages" configuration option. The database may not be able to order the request column type in which case, if sorted is true, the database may use a substitute column type.

$data_type is the SQL type. The types are constants defined by this module, to import them use:

 use EPrints::Database qw( :sql_types );
 

Supported types (n = requires $length argument):

Character data: SQL_VARCHAR(n), SQL_LONGVARCHAR, SQL_CLOB.

Binary data: SQL_VARBINARY(n), SQL_LONGVARBINARY.

Integer data: SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT.

Floating-point data: SQL_REAL, SQL_DOUBLE.

Time data: SQL_DATE, SQL_TIME.

The actual column types used will be database-specific.

User Comments


Basic SQL Operations

User Comments


do

$success = $db->do( $sql )

Execute the given $sql.

User Comments


prepare

$sth = $db->prepare( $sql )

Prepare the given $sql and return a handle on it.

Use the execute method on the returned DBI handle to execute the SQL:

 my $sth = $db->prepare_select( "SELECT 'Hello, World'" );
 $sth->execute;
 

User Comments


prepare_select

$sth = $db->prepare_select( $sql, [ %options ] )

Prepare a SELECT statement $sql and return a handle to it. After preparing a statement use execute() to execute it.

Returns a DBI statement handle.

The LIMIT SQL keyword is not universally supported, to specify this use the limit option.

Options:

 limit - limit the number of rows returned
 offset - return limit number of rows after offset
 

User Comments


execute

$success = $db->execute( $sth, $sql )

Execute the SQL prepared earlier in the $sth. $sql is only required for debugging purposes.

User Comments


update

$success = $db->update( $dataset, $data, $changed )

Updates a EPrints::DataObj from $dataset with the given $data. The primary key field (e.g. eprintid) value must be included.

Updates the ordervalues if the $dataset is ordered.

User Comments


_update

$rows = $db->_update( $tablename, $keycols, $keyvals, $columns, @values )

Updates $columns in $tablename with @values where $keycols equals $keyvals and returns the number of rows affected.

N.B. If no rows are affected, the result is still true, see DBI's execute() method.

This is an internal method.

User Comments


insert

$success = $db->insert( $table, $columns, @values )

Inserts @values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @values is a list of arrays containing values to insert. These will be quoted before insertion.

User Comments


insert_quoted

$success = $db->insert_quoted( $table, $columns, @qvalues )

Inserts values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @qvalues is a list of arrays containing values to insert. These will NOT be quoted before insertion - care must be exercised!

User Comments


delete_from

$success = $db->delete_from( $table, $columns, @values )

Perform a SQL DELETE FROM $table using $columns to build a where clause. @values is a list of array references of values in the same order as $columns.

If you want to clear a table completely use clear_table().

User Comments


count_table

$n = $db->count_table( $tablename )

Return the number of rows in the specified SQL table with $tablename.

User Comments


clear_table

$db->clear_table( $tablename )

Clears all records from the given table with $tablename. Use with caution!

User Comments


Quoting

User Comments


prep_int

$mungedvalue = EPrints::Database::prep_int( $value )

Escape numerical $value for an SQL statement. undef becomes NULL. Anything else becomes a number (zero if needed).

User Comments


prep_value

$mungedvalue = EPrints::Database::prep_value( $value )

Escape $value for an SQL statement. Modify value such that " becomes \" and \ becomes \\ and ' becomes \'.

User Comments


prep_like_value

$mungedvalue = EPrints::Database::prep_like_value( $value )

Escape $value for an SQL LIKE clause. In addition to ' " and \ also escapes % and _.

User Comments


quote_value

$str = $db->quote_value( $value )

Return a quoted version of $value. To quote a LIKE value you should use:

$db->quote_value( EPrints::Database::prep_like_value( $foo ) . '%' );
 

User Comments


quote_int

$str = $db->quote_int( $value )

Return a quoted integer for $value.

User Comments


quote_binary

$str = $db->quote_binary( $bytes )

Some databases (Oracle/PostgreSQL) require transforms of binary data to work correctly.

This method should be called on data $bytes containing null bytes or back-slashes before being passed on quote_value.

User Comments


quote_ordervalue

$str = $db->quote_ordervalue( $field, $value )

Some databases (Oracle) can't order by CLOBs so need special treatment when creating the ordervalues tables. This method allows any fixing-up required for string data $value for $field before it's inserted.

User Comments


quote_identifier

$str = $db->quote_identifier( @parts )

Quote a database identifier (e.g. table names). Multiple @parts will be joined by dots (.).

User Comments


prepare_regexp

$sql = $db->prepare_regexp( $col, $value )

The syntax used for regular expressions varies across databases. This method takes two quoted string and returns a SQL expression that will apply the quoted regexp $value to the quoted column $col.

User Comments


sql_as

$sql = $db->sql_AS()

Returns the syntactic glue to use when aliasing. SQL 92 databases will happily use AS but some databases (Oracle) will not accept it.

User Comments


sql_like

$sql = $db->sql_LIKE()

Returns the syntactic glue to use when making a case-insensitive LIKE. PostgreSQL requires ILIKE while everything else uses LIKE and the column collation.

User Comments


Counters

User Comments


counter_current

$n = $db->counter_current( $counter )

Return the value of the previous counter_next on $counter.

User Comments


counter_next

$n = $db->counter_next( $counter )

Return the next unused value for the named $counter. Returns undef if the $counter doesn't exist.

User Comments


counter_minimum

$db->counter_minimum( $counter, $value )

Ensure that the $counter is set no lower than $value. This is used when importing eprints which may not be in scrict sequence.

User Comments


counter_reset

$db->counter_reset( $counter )

Reset the $counter. Use with caution.

User Comments


next_doc_pos

$n = $db->next_doc_pos( $eprintid )

Return the next unused document position for the given $eprintid.

User Comments


Dataset Data

User Comments


exists

$boolean = $db->exists( $dataset, $id )

Return true if there exists an EPrints::DataObj from the $dataset with its primary key set to $id. Otherwise, return false.

User Comments


add_record

$success = $db->add_record( $dataset, $data )

Add the given $data as a new record in the given $dataset. $data is a reference to a hash containing values structured for a record in the that $dataset.

User Comments


remove

$success = $db->remove( $dataset, $id )

Attempts to remove the EPrints::DataObj with the primary key $id from the specified $dataset.

User Comments


Searching, caching and object retrieval

User Comments


cache_exp

$searchexp = $db->cache_exp( $cacheid )

Return the serialised search of a the cached search with $cacheid. Return undef if the $cacheid is invalid or expired.

User Comments


cache

$cacheid = $db->cache( $searchexp, $dataset, $srctable, [$order], [$list] )

Create a cache of the specified search expression from the SQL table $srctable.

If $order is set then the cache is ordered by the specified fields. For example -year/title orders by year (descending). Records with the same year are ordered by title.

If $srctable is set to LIST then order is ignored and the list of IDs is taken from the array reference $list.

If $srctable is set to ALL every matching record from $dataset is added to the cache, optionally ordered by $order.

User Comments


cache_table

$tablename = $db->cache_table( $id )

Return the name of the SQL table used to store the cache with $id.

User Comments


cache_userid

$userid = $db->cache_userid( $id )

Returns the userid associated with the cache with $id if that cache exists.

User Comments


get_cachemap

$cachemap = $db->get_cachemap( $id )

Return the cachemap with $<id>.

User Comments


search

$ids = $db->search( $keyfield, $tables, $conditions, [ $main_table_alias ] )

Return a reference to an array of $keyfield IDs - the results of the search specified by $conditions across the tables specified in the $tables hash where keys are tables aliases and values are table names.

If no $main_table_alias is specified then M is assumed.

User Comments


drop_cache

$db->drop_cache( $id )

Remove the cached search with the given $id.

User Comments


from_cache

$items = $db->from_cache( $dataset, $cacheid, [ $offset, $count, $justids ] )

Return a reference to an array containing all the items from the given $dataset that have IDs in the cache specified by $cacheid. The cache may be specified either by ID or serialised search expression.

$offset is an offset from the start of the cache and $count is the number of records to return.

If $justids is true then it returns just a reference to an array of the record IDs and not the objects themselves.

User Comments


drop_orphan_cache_tables

$c = $db->drop_orphan_cache_tables

Drop tables called cacheXXX where XXX is an integer. Returns the number of cache tables dropped.

User Comments


get_single

$obj = $db->get_single( $dataset, $id )

Return a single <EPrints::DataObj> from the given $dataset with primary key set to $id.

User Comments


get_all

$items = $db->get_all( $dataset )

Returns a reference to an array with all the <EPrints::DataObj>s from the given $dataset.

User Comments


get_cache_ids

@ids = $db->get_cache_ids( $dataset, $cachemap, $offset, $count )

Returns a list of $count IDs from $cache_id starting at $offset and in the order in the $cachemap.

User Comments


get_dataobjs

@dataobjs = $db->get_dataobjs( $dataset, [ $id, $id, ... ] )

Retrieves the records in $dataset with the given $id(s). If an $id doesn't exist in the database it will be ignored.

User Comments


get_values

$values = $db->get_values( $field, $dataset )

Return a reference to an array of all the distinct values of the EPrints::MetaField $field for the $dataset specified.

User Comments


sort_values

$values = $db->sort_values( $field, $values, [ $langid ] )

Sorts and returns the list of $values using the database.

$field is used to get the order value for each value. $langid (or $session->get_langid if unset) is used to determine the database collation to use when sorting the resulting order values.

User Comments


get_ids_by_field_values

$ids = $db->get_ids_by_field_values( $field, $dataset, [ %opts ] )

Return a reference to a hash table where the keys are specified $datasets's $field value IDs and the values are references to arrays of IDs.

User Comments


dequeue_events

@events = $db->dequeue_events( $n )

Attempt to dequeue upto $n events. May return between 0 and $n events depending on parallel processes and how many events are remaining in the queue.

User Comments


ci_lookup

$value = $db->ci_lookup( $field, $value )

This is a hacky method to support case-insensitive lookup for usernames, emails, etc. It returns the actual case-sensitive version of $value if there is a case-insensitive match for the $field.

User Comments


Password Validation and Secret Fields

User Comments


valid_login

$db->valid_login( $username, $password )

Returns whether the clear-text $password matches the stored crypted password for the $username.

User Comments


secret_matches

$db->secret_matches( $dataobj, $fieldname, $token [, $callback ] )

Returns whether the clear-text $token matches the stored crypted field with $fieldname for the $dataobj according to the $callback function.

If not set, $callback defaults to EPrints::Utils#crypt_equals.

User Comments


is_secret_set

$boolean = $db->is_secret_set( $dataobj, $fieldname )

Returns a boolean for whether the secret $fieldname for $dataobj has a value set.

User Comments


Database Schema Manipulation

User Comments


has_sequence

$boolean = $db->has_sequence( $name )

Returns true if a sequence of the given $name exists in the database. Otherwise, returns false.

User Comments


create_sequence

$success = $db->create_sequence( $name )

Creates a new sequence object with $name and initialises to zero.

User Comments


drop_sequence

$success = $db->drop_sequence( $name )

Deletes a sequence object with $name.

User Comments


has_column

$boolean = $db->has_column( $table, $column )

Return true if the named $table has the named $column in the database.

User Comments


drop_column

$success = $db->drop_column( $table, $column )

Drops the named $column from the named $table.

User Comments


get_primary_key

@columns = $db->get_primary_key( $tablename )

Returns a list of column names that comprise the primary key for the $tablename.

Returns an empty list if no primary key exists.

User Comments


index_name

$name = $db->index_name( $table, @cols )

Returns the name of the first index that starts with named columns @cols in the named $table.

Returns undef if no index exists.

User Comments


get_index_ids

$ids = $db->get_index_ids( $table, $condition )

Return a reference to an array of the distinct primary keys from the named SQL $table which match the specified $condition.

User Comments


create_index

$success = $db->create_index( $table, @columns )

Creates an index over @columns for named $table. Returns true on success, false otherwise.

User Comments


create_unique_index

$success = $db->create_unique_index( $tablename, @columns )

Creates a unique index over @columns for named $table. Returns true on success, false otherwise.

User Comments


create_foreign_key

$ok = $db->create_foreign_key( $main_table, $table, $key_field )

Create a foreign key relationship between named $main_table and named $table using $key_field.

This will cause records in $table to be deleted if the equivalent record is deleted from $main_table.

User Comments


get_tables

@tables = $db->get_tables( [ $dbname ] )

Returns a list of all the tables in the database.

$dbname specifies a particular database name of current connection has access to more than one database.

User Comments


has_table

$boolean = $db->has_table( $tablename )

Returns boolean dependent on whether a table of the $tablename exists in the database.

User Comments


create_table

$success = $db->create_table( $tablename, $setkey, @fields );

Creates a new table with $tablename based on @fields.

The first $setkey number of fields are used for its primary key.

User Comments


drop_table

$db->drop_table( @tables )

Delete the named @tables. Use with caution!

User Comments


rename_table

$db->rename_table( $table_from, $table_to )

Renames the table named $table_from to $table_to.

User Comments


swap_table

$db->swap_table( $table_a, $table_b )

Renames table named $table_a to $table_b and vice-versa.

User Comments


EPrints Schema Manipulation

User Comments


create_archive_tables

$success = $db->create_archive_tables()

Create all the SQL tables for all datasets.

User Comments


drop_archive_tables

$db->drop_archive_tables()

Destroy all tables used by EPrints in the database.

User Comments


create_version_table

$db->create_version_table

Make the version table (and set the only value to be the current version of EPrints).

User Comments


drop_version_table

$db->drop_version_table

Drop the version table.

User Comments


has_dataset

$db->has_dataset( $dataset )

Returns true if $dataset exists in the database and has all expected tables including ordervalues and index tables.

This does not check that all fields are configured - see </has_field>.

User Comments


has_dataset_index_tables

$db->has_dataset_index_tables( $dataset )

Returns true if index tables for $dataset exists of if this is not indexable.

User Comments


create_dataset_tables

$success = $db->create_dataset_tables( $dataset )

Creates all the SQL tables for the specified $dataset.

User Comments


drop_dataset_tables

$db->drop_dataset_tables( $dataset )

Drops all the SQL tables for the specified $dataset.

User Comments


create_dataset_index_tables

$success = $db->create_dataset_index_tables( $dataset )

Creates all the index tables for the specified $dataset.

User Comments


create_dataset_ordervalues_tables

$success = $db->create_dataset_ordervalues_tables( $dataset )

Creates all the ordervalues tables for the specified $dataset.

User Comments


has_field

$db->has_field( $dataset, $field )

Returns true if $field is in the database for $dataset.

User Comments


add_field

$db->add_field( $dataset, $field, [ $force ] )

Add $field to $dataset's tables.

If $force is true modify/replace an existing column. Use with care!

User Comments


remove_field

$db->remove_field( $dataset, $field )

Remove $field from $dataset's tables.

User Comments


rename_field

$ok = $db->rename_field( $dataset, $field, $old_name )

Rename the $field in the $dataset from its $old_name.

Returns true if the $field is successfully renamed.

User Comments


create_counters

$success = $db->create_counters

Create the counters used to store the highest current ID of eprints, users, etc.

User Comments


has_counter

$success = $db->has_counter( $counter )

Returns true if $counter exists.

User Comments


create_counter

$success = $db->create_counter( $name )

Create and initialise to zero a new counter with $name.

User Comments


remove_counters

$success = $db->remove_counters

Destroy all counters.

User Comments


drop_counter

$success = $db->drop_counter( $name )

Destroy the counter named $name.

User Comments


User Messages

User Comments


save_user_message

$message = $db->save_user_message( $userid, $m_type, $dom_m_data )

Save user message provided in XML DOM object $dom_m_data as a sanitized string in a EPrints::DataObj::Message using $m_type to define the message type and $userid for the ID of the user whose message it is.

User Comments


get_user_messages

@messages = $db->get_user_messages( $userid, %opts )

Get the messages for a user with ID $userid and clear messages if $opt{clear} is set.

User Comments


clear_user_messages

$db->clear_user_messages( $userid )

Clear all messages for user with ID $userid.

User Comments


SEE ALSO

To access database-stored objects use the methods provided by the following modules: EPrints::Repository, EPrints::DataSet.

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints 3.4. If not, see http://www.gnu.org/licenses/.

User Comments