Update Perl doc for new database framework (#303)

* Update Pelr doc for new database framework

* UPdated PR following cmadjar's comments.

* Minor corrections to the perldoc of Database.pm.

dicom-archive/updateMRI_Upload.pl

@@ -12,7 +12,7 @@ =head1 NAME
 
 =head1 SYNOPSIS
 
-updateMRI_Upload.pl [options] -profile prod -tarchivePath tarchivePath -source_location source_location
+updateMRI_Upload.pl [options] -profile prod -tarchivePath tarchivePath -source_location source_location -timeZone tz
 
 =over 2
 
@@ -143,7 +143,7 @@ =head1 AUTHORS
 my $Usage = "------------------------------------------
 $0 updates the mri_upload table to populate the fields
 
-Usage:\n\t $0 -profile <profile>
+Usage:\n\t $0 -profile <profile> -sourceLocation src -tarchivePath path [-verbose] [-globLocation] [-timeZone tz] 
 \n\n See $0 -help for more info\n\n";
 
 my @arg_table =

docs/scripts_md/ConfigOB.md

@@ -0,0 +1,95 @@
+# NAME
+
+NeuroDB::objectBroker::ConfigOB -- An object broker for configuration settings
+
+# SYNOPSIS
+
+    use NeuroDB::Database;
+    use NeuroDB::objectBroker::ConfigOB;
+    use TryCatch;
+
+    my $db = NeuroDB::Database->new(
+        userName     => 'user',
+        databaseName => 'my_db',
+        hostName     => 'my_hostname',
+        password     => 'pwd'
+    );
+
+    try {
+        $db->connect();
+    } catch(NeuroDB::DatabaseException $e) {
+        die sprintf(
+            "User %s failed to connect to %s on %s: %s (error code %d)\n",
+            'user',
+            'my_db',
+            'my_hostname',
+            $e->errorMessage,
+            $e->errorCode
+        );
+    }
+
+    .
+    .
+    .
+
+    my $configOB = NeuroDB::objectBroker::ConfigOB(db => $db);
+    my $tarchiveLibraryPath;
+    try {
+        $tarchiveLibraryPath = $configOB->getTarchiveLibraryPath();
+    } catch(NeuroDB::objectBroker::ObjectBrokerException $e) {
+        die sprintf(
+            "Failed to retrieve tarchive library path: %s",
+            $e->errorMessage
+        );
+    }
+
+# DESCRIPTION
+
+This class provides a set of methods to fetch specific configuration settings
+from the `Config` LORIS database.
+
+## Methods
+
+### new(db => $db) >> (constructor)
+
+Create a new instance of this class. The only parameter to provide is the
+`Database` object used to access the database.
+
+INPUT: the database object used to fetch the settings.
+
+RETURN: new instance of this class.
+
+### &$getConfigSettingRef($setting)
+
+Private method. This method fetches setting `$setting` from the LORIS table 
+Config. It will throw a `NeuroDB::objectBroker::ObjectBrokerException` if either
+the database transaction failed for some reason or it succeeded but returned no
+results (i.e. setting $setting does not exist).
+
+INPUT: name of the setting to fetch.
+
+RETURN: the setting value (as a string). If the setting value is NULL, then this
+         method will return `undef`.
+
+### getTarchiveLibraryDir()
+
+Gets the tarchive library dir.
+
+RETURN: value (string) of the tarchive library dir in the Config table.
+
+# TO DO
+
+Nothing planned.
+
+# BUGS
+
+None reported.
+
+# COPYRIGHT AND LICENSE
+
+License: GPLv3
+
+# AUTHORS
+
+LORIS community <loris.info@mcin.ca> and McGill Centre for Integrative
+Neuroscience

docs/scripts_md/Database.md

@@ -0,0 +1,140 @@
+# NAME
+
+NeuroDB::Database -- Provides a set of methods to run SQL statements on a database
+
+# SYNOPSIS
+
+    use NeuroDB::Database;
+    use TryCatch;
+
+    my $db = NeuroDB::Database->new(
+        userName     => 'user',
+        databaseName => 'my_db',
+        hostName     => 'my_hostname',
+        password     => 'pwd'
+    );
+
+    try {
+        $db->connect();
+    } catch(NeuroDB::DatabaseException $e) {
+        die sprintf(
+            "User %s failed to connect to %s on %s: %s (error code %d)\n",
+            'user',
+            'my_db',
+            'my_hostname',
+            $e->errorMessage,
+            $e->errorCode
+        );
+    }
+
+    .
+    .
+    .
+
+    try {
+        $db->pselect(
+            'SELECT * FROM candidate WHERE pscid = ?', 'MTL135'
+        );
+    } catch(NeuroDB::DatabaseException $e) {
+        die sprintf(
+            "SELECT on candidate table failed: %s (error code=%d)",
+            $e->errorMessage,
+            $e->errorCode
+        );
+    }
+
+# DESCRIPTION
+
+This class provides the basic `SELECT`, `INSERT`, `UPDATE` and `DELETE` methods
+for all object brokers. The methods of this class should only be used by
+the object brokers themselves (except `new` for creating a new database
+instance and `connect`). Scripts and 'non-broker' classes that need access
+to the database should rely on an appropriate object broker class to handle
+the requests.
+
+## Methods
+
+### `new(userName => $u, databaseName => $d, hostname => $h, password => $pwd, port =>$port)`  (constructor)
+
+Create a new instance of this class, without actually trying to connect
+to the database specified. All parameters are required except `port`, which
+defaults to 3306 if not specified. If the user name, database name or host
+name are the empty string, the constructor will call `die`.
+
+INPUTS:
+  - name of the user for the (upcoming) connection.
+  - name of the database.
+  - name of the host on which the database resides.
+  - password for the (upcoming) connection.
+  - port used for the (upcoming) connection (defaults to 3306 if not provided).
+
+RETURN: new instance of this class.
+
+### `connect()`
+
+Attempts to connect to the database using the connection parameters passed
+at construction time. This method will throw a `DatabaseException` if the
+connection could not be established.
+
+### `pselect($query, @args)`
+
+Executes a `SELECT` query on the database. This method will first `prepare`
+the statement passed as parameter before sending the request to the database.
+
+INPUTS: 
+  - `SELECT` query to execute (containing the argument placeholders if any).
+  - list of arguments to replace the placeholders with.
+
+RETURN: a reference to the array of records found. Each record is in fact a
+        reference to the list of values for the columns selected.
+
+### `insertOne($tableName, $valuesRef)`
+
+Inserts one record in a given database table with the specified column values.
+This method will throw a `DatabaseException` if the record cannot be inserted.
+
+INPUTS: 
+  - name of the table in which to insert the record.
+  - reference to a hash array describing the column names and their values
+    for the given record.
+
+RETURN: the ID of the record inserted.
+
+### `insert($tableName, $columnNamesRef, $valuesRef)`
+
+Inserts one record in a given database table with the specified column values.
+This method will throw a `DatabaseException` if the record cannot be inserted.
+
+INPUTS: 
+  - name of the table in which to insert the record.
+  - reference to an array containing the names of the columns whose values
+    will be modified by this `INSERT` statement.
+  - reference to an array of array references. This "matrix" contains the
+    values of each column for each record.
+
+### `disconnect()`
+
+Terminates the connection previously instantiated to the database if a 
+connection was previously established.
+
+### `DESTROY()`
+
+Object destructor: terminates the connection previously instantiated to the
+database (if any).
+
+# TO DO
+
+Nothing planned.
+
+# BUGS
+
+None reported.
+
+# COPYRIGHT AND LICENSE
+
+License: GPLv3
+
+# AUTHORS
+
+LORIS community <loris.info@mcin.ca> and McGill Centre for Integrative
+Neuroscience

docs/scripts_md/DatabaseException.md

@@ -0,0 +1,52 @@
+# NAME
+
+NeuroDB::DatabaseException -- Exception for database related errors.
+
+# SYNOPSIS
+
+    use NeuroDB::DatabaseException;
+
+    .
+    .
+    .
+
+    NeuroDB::DatabaseException->throw(
+        statement    => 'SELECT * from Foo WHERE x=? AND y=?',
+        args         => [1, 2],
+        errorCode    => $DBI::err,
+        errorMessage => $DBI::errstr
+    );
+
+# DESCRIPTION
+
+This class is the base class for database-related exceptions. You use this
+class by calling the `throw` method with the specified parameters (all of
+which are required). This will build a new instance of this class and throw
+it as expected. The throw method of this class will call `die` if the error
+code is zero and the error message is defined or if the error code is not
+0 and the error message is undefined.
+
+### `toString()`
+
+Default representation of this exception when used in a string context.
+Among other things, the returned string will be used for uncaught exceptions
+that make a script die. Note that the returned string can be useful for debugging
+purposes when trying to diagnose why a particular SQL statement did not execute
+successfully.
+
+# TO DO
+
+Nothing planned.
+
+# BUGS
+
+None reported.
+
+# COPYRIGHT AND LICENSE
+
+License: GPLv3
+
+# AUTHORS
+
+LORIS community <loris.info@mcin.ca> and McGill Centre for Integrative
+Neuroscience

docs/scripts_md/MRI.md

@@ -98,16 +98,18 @@ INPUTS:
 
 RETURNS: the determined objective, or 0
 
-### identify\_scan\_db($center\_name, $objective, $fileref, $dbhr)
+### identify\_scan\_db($center\_name, $objective, $fileref, $dbhr, $db, $minc\_location)
 
 Determines the type of the scan described by MINC headers based on
 `mri_protocol` table in the database.
 
 INPUTS:
-  - $center\_name: center's name
-  - $objective  : objective of the study
-  - $fileref    : file hash ref
-  - $dbhr       : database handle reference
+  - $center\_name   : center's name
+  - $objective     : objective of the study
+  - $fileref       : file hash ref
+  - $dbhr          : database handle reference
+  - $db            : database object
+  - $minc\_location : location of the MINC files
 
 RETURNS: textual name of scan type from the `mri_scan_type` table
 
@@ -148,13 +150,13 @@ INPUTS:
 
 RETURNS: 1 if in range, 0 if not in range
 
-### scan\_type\_id\_to\_text($typeID, $dbhr)
+### scan\_type\_id\_to\_text($typeID, $db)
 
 Determines the type of the scan identified by its scan type ID.
 
 INPUTS:
   - $typeID: scan type ID
-  - $dbhr  : database handle reference
+  - $db    : database object
 
 RETURNS: Textual name of scan type
 
@@ -164,7 +166,7 @@ Determines the type of the scan identified by scan type.
 
 INPUTS:
   - $type: scan type
-  - $dbhr: database handle reference
+  - $db  : database object
 
 RETURNS: ID of the scan type
 
@@ -311,6 +313,7 @@ INPUTS:
   - $data\_dir      : data directory (e.g. `/data/$PROJECT/data`)
   - $dest\_dir      : destination directory (e.g. `/data/$PROJECT/data/pic`)
   - $horizontalPics: boolean, whether to create horizontal pics (1) or not (0)
+  - $db            : database object used to interact with the database.
 
 RETURNS: 1 if the pic was generated or 0 otherwise.
 

docs/scripts_md/MRIProcessingUtility.md

@@ -8,7 +8,7 @@ utilities
     use NeuroDB::ProcessingUtility;
 
     my $utility       = NeuroDB::MRIProcessingUtility->new(
-                          \$dbh,    $debug,  $TmpDir,
+                          $db, \$dbh,    $debug,  $TmpDir,
                           $logfile, $LogDir, $verbose
                         );
 
@@ -43,13 +43,20 @@ scripts of LORIS.
 
 ## Methods
 
-### new($dbhr, $debug, $TmpDir, $logfile, $verbose) >> (constructor)
+### new($db, $dbhr, $debug, $TmpDir, $logfile, $verbose, $profile) >> (constructor)
 
 Creates a new instance of this class. The parameter `$dbhr` is a reference
 to a `DBI` database handle, used to set the object's database handle, so that
 all the DB-driven methods will work.
 
-INPUT: `DBI` database handle
+INPUT: 
+  - $db      : database object
+  - $dbhr    : DBI database handle reference
+  - $debug   : degug flag (1 for debug, 0 otherwise)
+  - $TmpDir  : temporay directory name (for tarchive extraction)
+  - $logfile : log file name
+  - $verbose : boolean flag for verbose behavior (1 lots of messages, 0 otherwise)
+  - $profile : path of the profile file
 
 RETURNS: new instance of this class.