Maxscape::Database::Base Package

Synopsis

use Maxscape::Database::Base;

&Maxscape::Database::Base::InstallDriver ();
&Maxscape::Database::Base::registerDatabaseProduct($DataBase::Product);
&Maxscape::Database::Base::registerDatabases($ServerConfiguration->Databases);

Description

Basis maXscape database initialisation functions. Since the maxscape server calls them by default, they may not be called within application functions included via the maXscape application plugin.

The package is usefull to write programms, that have to connect to the Maxscape server databases.

List of Member Functions

  1. InitAdminCursor
  2. InitDatabaseHandler
  3. initDBConnection
  4. InstallDriver
  5. listConfiguredServer
  6. registerDatabaseProduct
  7. registerDatabases

Member Functions

InstallDriver

Synopsis

&Maxscape::Database::Base::InstallDriver ( %P );

Description

Installs the configured database driver. As a side effect sets the global variable $Database::DatabaseDriver.

Examples

my $Driver;
unless ( $Driver = &Maxscape::Database::Base::InstallDriver (
                     DatabaseType   => 'oracle',
                     [ Attributes   => \%Attributes, ]
                     [ CompatMode   =>  1, ]
                     [ Warn         => 0, ]
                     [ ChopBlanks   => 1 ]) )
{
  print STDERR ("Can't install database driver.");
}

registerDatabaseProduct

Synopsis

&Maxscape::Database::Base::registerDatabaseProduct($DatabaseProduct);

Description

Registers the database product type to the system and sets the necessary configuration variables.

The function is called by the runtime system and must not be called within applications included via the maXscape application plugin.

Examples

my $DataBaseProduct = 'mysql'; # e.g. msql, mysql, oracle
&Maxscape::Database::Base::registerDatabaseProduct($DatabaseProduct);

initDBConnection

Synopsis

Maxscape::Database::Base::initDBConnection ( $WebServerName );

Description

Initializes the connections to the database.

Examples





InitAdminCursor



Synopsis


&Maxscape::Database::Base::InitAdminCursor();




Description



Registers an additional database object with an own database connection
to the process.




Examples


$WebServer->{ConfigAdminCursor} &&
                 &Maxscape::Database::Base::InitAdminCursor();





InitDatabaseHandler



Synopsis


&Maxscape::Database::Base::InitDatabaseHandler ( $WebServerName );




Description



Installs the database driver, creates a 'DataBase' object and
connects this object to the database named '$WebServerName'.




Examples


$WebServer->{ConfigAdminCursor} &&
                 &Maxscape::Database::Base::InitAdminCursor();





registerDatabases



Synopsis


my %DataBases = ( ... );
&Maxscape::Database::Base::registerDatabases(\%Databases);




Description



Registers the configurated databases to the system. Takes a hash
reference defining the server's databases.





listConfiguredServer



Synopsis


my @ConfiguredServerList = &Maxscape::Database::Base::listConfiguredServer();




Description



Lists the configurated application server.







Maxscape::Database Package



Synopsis


use Maxscape::Database;




Description



The Maxscape::Database package supplies the basic functionality to deal with
the server's database, especially the Content Database. It provides a portable
API, that masks database product specifica. To use the package the software
must previously be set up with the functions of the Maxscape::Database::Base
package.




Examples


To access the data in the database, you can use the methods provided by the
run time objects of this class. For example, if you want to query a self
defined database table MY_TABLE', you can use the following code (not tested): 

 sub my_prefix_myFunction {
   my $self = @_;

   my $Text;
   my $TableName = 'myTable';
   my $where     = "myColumn='blabla'";
   my $Query     = "SELECT * from $TableName where $where";

   # create a new cursor object connected to the current database.
   my $Cursor = Maxscape::Database->newCursor ();

   if (!$Cursor->Sql ($Query)) {
     return $Cursor->printError;
   }

   my $Counter = 0;
   my @Row;
   while (1)
   {
     # fetch the database rows
     @Row = $Cursor->fetchRow;
     last if $#Row == -1 ;
     $Counter++;

     # e.g. return the rows of the first table column.
     $Text .= "$Counter: 1. Spalte" . $Row[0] . $::LF;
   }
   return $Text;
 }




List of Member Functions
    

  1. changeRecord
    2. 

  2. changeRecords
    3. 

  3. checkTextColumnSize
    4. 

  4. checkTextFieldLength
    5. 

  5. close
    6. 

  6. ColumnType
    7. 

  7. connect
    8. 

  8. connectedDatabaseName
    9. 

  9. copyNodeRecord
    10. 

  10. copyRecord
    11. 

  11. CountRecords
    12. 

  12. DatabaseExists
    13. 

  13. DatabaseName
    14. 

  14. DB_QueryColumnNames
    15. 

  15. DB_QueryColumnNamesTypesSizes
    16. 

  16. DB_QueryColumnSizes
    17. 

  17. DB_QueryColumnTypes
    18. 

  18. DB_TableColumnNamesTypesSizes
    19. 

  19. deleteRecord
    20. 

  20. deleteRecords
    21. 

  21. escapeTableName
    22. 

  22. escapeTableName
    23. 

  23. fetchColumns
    24. 

  24. fetchColumnsAsHash
    25. 

  25. fetchListOfHashes
    26. 

  26. fetchRow
    27. 

  27. fetchRowArray
    28. 

  28. fetchRowAsHash
    29. 

  29. fetchRowToHash
    30. 

  30. finish
    31. 

  31. getRecordHashRef
    32. 

  32. insertRecord
    33. 

  33. insertRecordFromFile
    34. 

  34. insertRecordFromString
    35. 

  35. lockTables
    36. 

  36. MaxRecord
    37. 

  37. MaxTextFieldlength
    38. 

  38. new
    39. 

  39. newCursor
    40. 

  40. preventSQLInjection
    41. 

  41. printError
    42. 

  42. QueryColumnIndex
    43. 

  43. QueryColumnNamesTypesSizes
    44. 

  44. quote
    45. 

  45. RowToHash
    46. 

  46. selectDataBase
    47. 

  47. showDatabases
    48. 

  48. Sql
    49. 

  49. TableColumnIndex
    50. 

  50. TableColumnNamesTypesSizes
    51. 

  51. TableQueryColumnValuePair
    52. 

  52. TextFieldlength
    53. 

  53. unlockTables
    54. 

  54. WebServerName
    55. 



Member Functions
    




new



Synopsis


my $Cursor = Maxscape::Database->new ( WebServerName => $ApplicationServerName);




Description



Makes a new  Maxscape::Database object connected to the application server's
database.  Assumes that the system is previously set up by the functions of the
Maxscape::Database::Base package.


Within application functions, allways use the Maxscape::Database->newCursor()
function instead.





newCursor



Synopsis


my $Cursor = Maxscape::Database->newCursor( [ $origCursor ]);




Description



Makes a new Maxscape::Database object from an existing. Assumes that the system
is previously set up by the functions of the Maxscape::Database::Base class.





printError



Synopsis


my $Cursor = Maxscape::Database->printError($ErrorMessage);




Description



Prints error messages conserning the database.





finish



Synopsis


my $DatabaseName = $Cursor->finish;




Description



Closes a cursor to an Application Database.





close



Synopsis


my $DatabaseName = $Cursor->close;




Description



Closes a connection to the database.





DatabaseName



Synopsis


my $DatabaseName = $Cursor->DatabaseName();




Description



Returns the name of the connected application server's database.





WebServerName



Synopsis


my $WebServerName = $Cursor->WebServerName();




Description



Returns the name of the connected application server.





connect



Synopsis


unless (my $Database->connect ()) {
  print $self->printError("Error");
}




Description



Connects the database object to the related database. Usualy it is not necessary
to call this function within applications pluged in via tha application plugin
mechanism, cause all database connections are set up by the
system.





selectDataBase



Synopsis


my $OK = $Cursor->selectDataBase ($DatabaseName);




Description



Selects the appliction server's database given by the $DatabaseName parameter.




Examples


my $DatabaseName = 'Test';
unless ($Cursor->selectDataBase( $DatabaseName )) {
  $self->printError ("Error in fct. selectDataBase $DatabaseName.");
  return undef;
}





connectedDatabaseName



Synopsis


$DatabaseName = $Cursor->connectedDatabaseName();




Description



Returns the name of the connected database.




Examples






lockTables



Synopsis


$Cursor->lockTables('FORUM', 'WRITE');




Description



Locks a table.





unlockTables



Synopsis


$Cursor->unlockTables();




Description



Unlocks a table.





showDatabases



Synopsis


return $DBConnection->showDatabases();




Description



Shows the configured databases. Returns an array.





DatabaseExists



Synopsis


my $DatabaseExists = $DBConnection->DatabaseExists ($DatabaseName, \@allDatabaseNames);




Description



Checks if a database exists.





TableColumnNamesTypesSizes



Synopsis


my ($DB_ColumnNames, $DB_ColumnTypes, $DB_ColumnSizes,
    $internalDB_ColumnTypes, $internalDB_ColumnSizes)
      = $self->{Cursor}->TableColumnNamesTypesSizes ($TableName);




Description



Returns arrays containing the column names, internal and DB database
types and sizes of the columns of a Table





DB_TableColumnNamesTypesSizes



Synopsis


$Cursor->DB_TableColumnNamesTypesSizes('MY_TABLE');




Description



Returns references to three arrays, containing the names, types and sizes of
the taken database table (e.g. 'MY_TABLE').




Examples


my ($ColumnNames, $ColumnTypes, $ColumnSizes) =
      $self->{Cursor}->DB_TableColumnNamesTypesSizes ($Table);

foreach $ColumnName (@{$ColumnNames}) {
  ...
}





TableColumnIndex



Synopsis


my $TableColumnIndex = $self->{Cursor}->TableColumnIndex
                                          ($ColumnNames, $ColumnName);




Description



Returns the index of '$ColumnName' given by the array reference '$ColumnNames',
begining from 0. If nothing is found returns 'undef'.





escapeTableName



Synopsis


$Tables[$i] = $self->escapeTableName ($Tables[$i]);




Description



Returns the plain table name.





escapeTableName



Synopsis


$Tables[$i] = $self->escapeTableName ($Tables[$i]);




Description



Returns the plain table name.





TableQueryColumnValuePair



Synopsis


$ColumnValuePair = $DBConnection->TableQueryColumnValuePair (
                     $ColumnName, $ColumnValue, $ColumnType,
                     $ConcatenateSeparator
);




Description








Sql



Synopsis


$Cursor->Sql($Query, [ $DatabaseName ]);




Description



Sends a SQL query to an appliction server's database. Selected data
are then processed by the fetch functions.




Examples


unless ($Cursor->Sql("select foo from table where COLUMN='bar'")) {
  return "Error";
}
my @Row = $Cursor->fetchRow ();
return $Row[0];





fetchRow



Synopsis


my @Row = $Cursor->fetchRow ();




Description



Fetches the data from a previously initiated query. Returns an array, that
contains the database record.




Examples


my @Row;
while (1) {
  @Row = $Cursor->fetchRow ();
  last if ($#Row < 0);
  if ($Row[1] eq 'bar') {
    print "Foo: $Row[3]";
  }
}





fetchRowArray



Synopsis


my $ArrayReference = $Cursor->fetchRowArray ();




Description



Fetches the data from a previously initiated query. Returns a reference
to an array, that contains the database record.





fetchRowAsHash



Synopsis


my $RowHashReference = $Cursor->fetchRowAsHash ();




Description



Fetches the data from a previously issued query. Returns a reference
to a hash, that contains the database record.




Examples


my $RowHashReference = $Cursor->fetchRowAsHash ();

my $FooValue = ${$RowHashReference}{FOO_COLUMN};





fetchRowToHash



Synopsis


$Cursor->fetchRowToHash($HashReference);




Description



Fetches the data from a previously initiated query and adds it to the taken
'$HashReference' hash reference parameter.





RowToHash



Synopsis


$Cursor->RowToHash($ListReference);




Description



Stores the data from a previously query and returns a
hash reference.





fetchColumns



Synopsis


my $Row = { $Cursor->fetchColumns ("select COLUMNS from TABLE") };




Description



Fetches the specified COLUMNS from the database table.
Returns a hash of arrays, whereas the hash key is the column name and
the array contains the values of the COLUMNS.





fetchListOfHashes



Synopsis


my $Row = $Cursor->fetchListOfHashes ("select COLUMNS from TABLE");




Description



Fetches the specified records from the database table.
Returns a list of hashs, whereas the hash key is the column name and
the array contains the list of records as given by the SQL query.





fetchColumnsAsHash



Synopsis


my $PropertyHash = $self->{Cursor}->fetchColumnsAsHash ( %P );




Description



Returns a reference to a hash, where the hash key is the value of the
'HashKeyColumnName' column and corresponding hash value is the value of the
'HashValueColumnName' column.




Examples


my $PropertyHash = $self->{Cursor}->fetchColumnsAsHash (
               TableName           => 'WEB_SERVER',
               HashKeyColumnName   => 'PROPERTY_NAME',
               HashValueColumnName => 'PROPERTY_VALUE',
               where               => "PROPERTY_KEY = '$WebServerName'",
               order               => 'PROPERTY_NAME'
);
my $PropertyValue = ${$PropertyHash}{'myProperty'};





QueryColumnNamesTypesSizes



Synopsis


my ($DB_ColumnNames, $DB_ColumnTypes, $DB_ColumnSizes,
     $internalDB_ColumnTypes, $internalDB_ColumnSizes)
                     = $Cursor->QueryColumnNamesTypesSizes();




Description



Returns arrays containing the column names, internal and DB database
types and sizes of the columns from the last SQL database query.





DB_QueryColumnNamesTypesSizes



Synopsis


my @DB_QueryColumnNames = @{$self->DB_QueryColumnNamesTypesSizes ()};




Description



Returns an array containing the database names, types and sizes of the columns
from the last SQL database query.





DB_QueryColumnNames



Synopsis


my @DB_QueryColumnNames = @{$self->DB_QueryColumnNames ()};




Description



Returns an array containing the names of the columns from the last SQL
database query.





DB_QueryColumnTypes



Synopsis


my @DB_QueryColumnTypes = @{$self->DB_QueryColumnTypes ()};




Description



Returns an array containing the types of the columns from the last SQL
database query.





ColumnType



Synopsis


my $nternalColumnType = $self->ColumnType($ColumnType);




Description



Return the internal representation of a database column type.





DB_QueryColumnSizes



Synopsis


my @DB_QueryColumnSizes = @{$self->DB_QueryColumnSizes ()};




Description



Returns an array containing the sizes of the columns from the last SQL
database query.





QueryColumnIndex



Synopsis


my $QueryColumnIndex = $self->{Cursor}->QueryColumnIndex ($ColumnName);




Description



Returns the index of '$ColumnName' from the last SQL database query.
If nothing is found returns 'undef'.





MaxRecord



Synopsis


my $MaxRecord = $Cursor->MaxRecord (%P);




Description



Counts the records of a table.




Examples


my $MaxRecord = $Cursor->MaxRecord (TableName   => $TableName,
                                    CountColumn => $CountColumn,
                                    where       => $where,
                                    GroupBy     => $GroupBy,);





CountRecords



Synopsis


my $CountRecords = $Cursor->CountRecords ( %P );




Description



Returns min, max and count of the CountRecords column.




Examples


my ($MinRecord, $MaxRecord, $RecordCount) = $Cursor->CountRecords (
      TableName   => $TableName,
      CountColumn => $CountColumn,
      where       => $where,
      GroupBy     => $GroupBy,);





TextFieldlength



Synopsis


my $TextFieldlength = $Cursor->TextFieldlength();




Description



Returns the maximal number of bytes, a given database product may allocate
for a given database text field. (This does not equal to the number of bytes).





MaxTextFieldlength



Synopsis


my $MaxTextFieldlength = $Cursor->MaxTextFieldlength();




Description



Returns the maximal number of bytes, that can be stored in a database
text field (default=4000 bytes for compatibility with oracle 8).





checkTextFieldLength



Synopsis


$DBConnection->>checkTextFieldLength($Text);




Description



Check the length of a text to fit the purpose.




Examples


if ($self->checkTextFieldLength($Text) > -1) {
  # do something usefull...
} else {
  return $self->printError("Error in function ...:");
}





checkTextColumnSize



Synopsis


$Cursor->checkTextColumnSize($ColumnName, $ColumnType,
                             $ColumnSize, $ColumnValue);




Description




Returns -1, if the size exceeds the maximal size of the column, else
returns the size of the variable '$ColumnValues' in bytes.



The variable '$ColumnType' may be in [ 'char', 'text' ]. '$ColumnSize' is the
size in bytes.




Examples


if ($self->checkTextColumnSize($ColumnName, $ColumnType,
                               $ColumnSize, $ColumnValue) > -1) {
  # do something usefull...
} else {
  return $self->printError("Error in function ...:");
}





insertRecord



Synopsis


my $Message = $Cursor->insertRecord(TableName    => 'MY_TABLE',
                                    ColumnValues => $Page->{CGI});




Description



Inserts the values of the taken hash reference 'ColumnValues' to the table
'MY_TABLE'.




Examples


my $Cursor = Maxscape::Database->newCursor();

my $Message = $Cursor->insertRecord('TableName'    => 'MY_TABLE',
                                    'ColumnValues' => $self->{CGI});
if ($Message ne 'OK') {
  return "Error: $Message$::BR";
}
my $Message = $Cursor->insertRecord(
                TableName       => 'USER_PROFILE',
                ColumnValues    => \%{
                 { USER_ID         => $self->{USER_ID},
                   PROPERTY_NAME   => $CGI->{'USER_PROFILE.PropertyName'},
                   PROPERTY_VALUE  => $CGI->{'USER_PROFILE.PropertyValue'}
                 },
          });





insertRecordFromString



Synopsis


$Text .= $self->{Cursor}->insertRecordFromString ( %P );




Description



Inserts the values of the taken string 'Columns' to the table 'TableName'.
'MY_TABLE'.




Examples


my $TableName = 'MY_TABLE';
$Text .= $self->{Cursor}->insertRecordFromString(
                           'TableName'       => $TableName,
                           'Columns'         => $Columns,
                           'ColumnsToInsert' => $ColumnsToInsert
         );





insertRecordFromFile



Synopsis


return $self->{'Cursor'}->insertRecordFromFile (
         'TableName' => 'MY_TABLE',
         'File'      => "/maxscape/server/'server'/tables/$File.sql",
         'FieldsToChange' => { '0' => $NODE_NUMBER });
       );




Description



Inserts the 'SQL insert statements' contained in the file 'File' into the
table 'MY_TABLE'.





getRecordHashRef



Synopsis


my $RecordAsHash = $self->{Cursor}->getRecordHashRef(
                                      $QueryColumns, $TableName, $where
                   );




Description



Get exactly one record as a hash reference from the database.




Examples


my $QueryColumns = '*';
my $TableName    = 'USER_PROFILE';
my $where        = "USER_ID='Foo' and PROPERTY_NAME='bar'";

my $RecordAsHash = $self->{Cursor}->getRecordHashRef(
                         $QueryColumns, $TableName, $where);

my $Text = ${$RecordAsHash}{PROPERTY_VALUE};





changeRecord



Synopsis


my $ErrorText = $Cursor->changeRecord (
                   TableName    => $TableName,
                   where        => "(NODE_NUMBER = $PageNumber)",
                   ColumnValues => { MODIFICATION_DATE => $Time });




Description



Changes the record(s) given by the functions parameters.




Examples


my $ErrorText = $Cursor->changeRecord (
                     TableName     => $TableName,
                     ColumnNames   => [ $ColumnName ],
                     ColumnTypes   => [ $Field{Type} ],
                     ColumnSizes   => [ $Field{Size} ],
                     where         => $self->{FieldKey},
                     ColumnValues  => { $ColumnName => "$FieldValueFromCGI" },
          );





changeRecords



Synopsis


$Cursor->changeRecords ( %P );




Description



So far, only used in the 'Maxscape::WebServer::UserAdmin' package.





copyRecord



Synopsis


$Message = $self->{Cursor}->copyRecord(
     'TableName'           => $TableName,
     'FieldsToChangeByName' => { 'NODE_NUMBER' => $NewPageNumber },
     'ColumnValues'         => $CGI,
     'where'                => $where);
if ($Message) {
  $ErrorText .= "$self->{ClassName}-err-2: copyRecord: $Message$::BR";
}





Description








copyNodeRecord



Synopsis


$Message = $self->{Cursor}->copyNodeRecord (
     'TableName'           => $TableName,
     'FieldsToChangeByName' => { 'NODE_NUMBER' => $NewPageNumber },
     'ColumnValues'         => $CGI,
     'where'                => $where);
if ($Message) {
  $ErrorText .= "$self->{ClassName}-err-2: copyNodeRecord: $Message$::BR";
}





Description








deleteRecord



Synopsis


my $ErrorText = $Cursor->deleteRecord('MY_TABLE', "COLUMN='foo'")




Description



Deletes the records given by the where clause (e.g. "COLUMN='foo'") from
the table (e.g. 'MY_TABLE').




Examples


my $ErrorText = $Cursor->deleteRecord('ELEMENTS using NODE, ELEMENTS',
                                      "NODE.NODE_CATEGORY='/deleteMe");





deleteRecords



Synopsis


my $ErrorText = $Cursor->deleteRecords('USERS', $whereClauses);




Description



Deletes records of a table, selected by the where clause.





quote



Synopsis


my $quotedText = $Cursor->quote($Text);




Description



Calls DBI's quote function.





preventSQLInjection



Synopsis


my $Text = $Cursor->preventSQLInjection ($Text);




Description



Removes dangerous SQL injection characters.






1


  






  

    
      Next ∙ Previous ∙ Top ∙ Join ∙ Contact
    
    
     © Maxscape