4.16. SQL::Datasource Class

Note: This class is not available with the PO_NO_DATABASE parse option.

The Datasource class is the high-level Qore interface to Qore's DBI layer, and as such, Datasource objects allow Qore programs to access databases that have a Qore DBI driver. The Datasource class will attempt to load any DBI driver that is not currently loaded in the constructor. For connection pooling support, see the DatasourcePool class.

Datasource objects will implicitly call Datasource::open() if no connection has yet been established and a method is called requiring a connection to the database server. Therefore any method that requires communication with the database server can also throw any exception that the open method can throw.

Some Qore DBI drivers allow "select" queries to be executed through the Datasource::exec() method, and allow SQL commands (procedure calls, etc) to be executed through the Datasource::select() method, and some DBI drivers do not (depends on the underlying DB API). At any rate, the transaction lock is set when auto-commit is disabled and when the Datasource::exec() or Datasource::beginTransaction() methods are executed as documented above. Therefore executing a transaction relevant command through the Datasource::select() method while auto-commit mode is disabled and a transaction has not yet started will not result in the transaction lock being allocated to the current thread and therefore could cause transaction errors when sharing the Datasource object between multiple threads.

Only databases with an existing Qore DBI driver can be accessed through the Qore Datasource class.

All Qore DBI drivers set new connections to use transaction isolation level "read committed".

The Datasource class provides consistent, high-level, per-connection locking on requests at a level above the DBI drivers to ensure that the communication between clients and servers is properly serialized.

4.16.1. Datasource Binding By Value and By Placeholder

All Datasource methods accepting SQL strings to execute understand a special syntax used in the query string to bind Qore data by value and to specify placeholders for output variables (for example, when executing a stored procedure or database function). Placeholder binding is DBI driver specific, but binding by value is supported with the same syntax in all drivers. Additionally, the %d numeric specifier is supported equally in all Qore DBI drivers.

To bind qore data values directly in a binary format in an SQL command, use %v in the command string, and include the value as an argument after the string. Binding by value means that Qore's DBI driver will take care of formatting the data properly for use in the query with the database server. That means that strings do not need to be quoted, date/time values do not need special formatting, binary object (with BLOB columns, for example) can be used directly in queries, etc.

Here is an example:

$rows = $db.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);

To insert a numeric value or a literal 'null' in a query, use %d in the command string, and include the value as an argument after the string. If the value is NOTHING or NULL, a literal 'null' will be written to the string; otherwise the argument is converted to a floating-point value or integer if necessary and written to the string. This is useful for working with DECIMAL (NUMERIC, NUMBER) types in a database-independent way; for example PostgreSQL servers do not do type conversions to DECIMAL types when a string, integer, or float is bound by value, therefore to ensure that integral decimal values can be used in a database-independent way (with 'null' substitution when no value is bound), it's best to use the %d code in the command string instead of %v.

For binding placeholders for output variables, write a unique name in the string and prefix it with a colon (ex: :code). In this case the method will return a hash of the output variables using the placeholder names as keys, but without the colon prefix. By default, a string type will be bound to the position. To bind other variable types to placeholder positions, include the type constant (see Type Constants) as an argument after the command string. For BLOBs, use Binary, for CLOBs, use the string "clob" (constants will be provided in a future release). Not all DBI drivers require placeholder buffer specifications; see the documentation for the DBI driver in question for more information and examples regarding placeholder buffer specifications.

4.16.2. Datasource Transaction Locks

Datasource objects have an internal transaction lock which will be grabbed when the Datasource::exec(), Datasource::vexec() or Datasource::beginTransaction() methods are executed and autocommit is not enabled. This enables a single datasource to be safely used for transaction management by several threads simultaneously. Note that an exception in a Datasource method that would acquire the lock (such as the Datasource::exec() method) when it's not already held, will have the effect that the transaction lock is not acquired.

Any thread attempting to do transaction-relevant actions on a Datasource with auto-commit disabled while a transaction is in progress by another thread will block until the thread currently executing a transaction executes the Datasource::commit() or Datasource::rollback() methods (or the Datasource is deleted, reset, or closed, in which case the lock is released and an exception is raised as well).

There is a timeout associated with the transaction lock; if a thread waits for the transaction lock for more than the timeout period, then an exception will be raised in the waiting thread. The timeout value can be read and changed with the Datasource::getTransactionLockTimeout() and Datasource::setTransactionLockTimeout() methods, respectively. The default transaction lock timeout value is 120 seconds.

Table 4.705. SQL::Datasource Method Overview

Method

Except?

Description

Datasource::constructor()

Y

Creates the Datasource object; attempts to load a DBI driver if the driver is not already present in Qore.

Datasource::destructor()

Y

Destroys the object.

Datasource::copy()

N

Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.

Datasource::open()

Y

Opens a connection to a database.

Datasource::close()

N

Closes the connection to the database.

Datasource::commit()

Y

Commits the transaction and releases the transaction lock.

Datasource::rollback()

Y

Rolls back the transaction and releases the transaction lock.

Datasource::setAutoCommit()

N

Turns autocommit on or off for this object.

Datasource::exec()

Y

Executes SQL code on the DB connection.

Datasource::vexec()

Y

Executes SQL code on the DB connection, taking a list for all bind arguments.

Datasource::select()

Y

Executes a select statement on the server and returns the results in a hash (column names) of lists (rows).

Datasource::vselect()

Y

Executes a select statement on the server and returns the results in a hash (column names) of lists (rows), taking a list for all bind arguments.

Datasource::selectRow()

Y

Executes a select statement on the server and returns the first row as a hash (column names and values).

Datasource::vselectRow()

Y

Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments.

Datasource::selectRows()

Y

Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values).

Datasource::vselectRows()

Y

Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments.

Datasource::beginTransaction()

Y

Manually grabs the transaction lock

Datasource::setUserName()

N

Sets the username parameter for the next open.

Datasource::getUserName()

N

Returns the username parameter.

Datasource::setPassword()

N

Sets the password parameter for the next open.

Datasource::getPassword()

N

Returns the password parameter.

Datasource::setDBName()

N

Sets the DB name parameter for the next open.

Datasource::getDBName()

N

Returns the dbname parameter.

Datasource::setDBCharset()

N

Sets the charset parameter for the next open.

Datasource::getDBCharset()

N

Returns the DBI driver specific charset name for the current connection.

Datasource::getOSCharset()

N

Returns the Qore charset name for the current connection.

Datasource::setHostName()

N

Sets the hostname parameter for the next open.

Datasource::getHostName()

N

Returns the hostname parameter.

Datasource::setPort()

N

Sets the port parameter for the next open.

Datasource::getPort()

N

Returns the port parameter.

Datasource::getDriverName()

N

Returns the name of the driver used for the object.

Datasource::setTransactionLockTimeout()

N

Sets the transaction lock timeout value in milliseconds. Set to 0 for no timeout.

Datasource::getTransactionLockTimeout()

N

Retrieves the transaction lock timeout value as an integer in milliseconds.

Datasource::getServerVersion()

Y

Returns the driver-specific server version data for the current connection.

Datasource::getClientVersion()

N

Returns the driver-specific client library version data. Not implemented by all drivers.


4.16.3. Datasource::constructor()

Synopsis

Creates a Datasource object. The constructor requires the datasource type as the first argument

Usage
new Datasource(driver_name, [username], [password], [dbname], [charset_name], [hostname], [port])
Example
$db = new Datasource(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5432);

Table 4.706. Arguments for Datasource::constructor()

Argument

Type

Description

driver_name

String

The name of the DBI driver for the Datasource. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver.

[username]

String

The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor.

[password]

String

The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor.

[dbname]

String

The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor.

[charset_name]

String

The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead.

[hostname]

String

The host name for the new connection (not used by some DBI drivers). Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor.

[port]

Integer

The port number for the new connection (not used by some DBI drivers). Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor.


Table 4.707. Return Values for Datasource::constructor()

Return Type

Description

Object

The Datasource object created


Table 4.708. Exceptions Thrown by Datasource::constructor()

err

desc

DATASOURCE-PARAMETER-EEROR

Missing DBI driver identifier as first argument.

DATASOURCE-UNSUPPORTED-DATABASE

Could not load a driver for the database identified.


4.16.4. Datasource::destructor()

Synopsis

Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object.

Usage
delete lvalue
Example
delete $db;

Table 4.709. Exceptions Thrown by Datasource::destructor()

err

desc

DATASOURCE-TRANSACTION-EXCEPTION

The Datasource was destroyed while a transaction was still in progress; the transaction will be automatically rolled back.


4.16.5. Datasource::copy()

Synopsis

Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.

Usage
Datasource::copy()
Example
$new_ds = $db.copy();

Table 4.710. Arguments for Datasource::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.711. Return Values for Datasource::copy()

Return Type

Description

Datasource Object

Returns a new Datasource object with the same driver as the original and copies of all the connection parameters.


4.16.6. Datasource::beginTransaction()

Synopsis

Manually grabs the transaction lock. This method should be called when the Datasource object will be shared between more than 1 thread, and a transaction will be started with a Datasource::select() method.

Usage
Datasource::beginTransaction()
Example
$db.beginTransaction();

Table 4.712. Arguments for Datasource::beginTransaction()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.713. Return Values for Datasource::beginTransaction()

Return Type

Description

n/a

This method return no value.


Table 4.714. Exceptions Thrown by Datasource::beginTransaction()

err

desc

AUTOCOMMIT-ERROR

Cannot start a transaction when autocommit is enabled.

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock.


4.16.7. Datasource::open()

Synopsis

Opens a connection to the datasouce, using the connection parameters already set.

Usage
Datasource::open()
Example
$db.open();

Table 4.715. Arguments for Datasource::open()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.716. Return Values for Datasource::open()

Return Type

Description

Integer

Returns 0 for success, -1 for error.


Table 4.717. Exceptions Thrown by Datasource::open()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.8. Datasource::close()

Synopsis

Closes the connection to the database. If any actions are in progress on the database, the close call will block until the actions complete.

Usage
Datasource::close()
Example
$db.close();

Table 4.718. Arguments for Datasource::close()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.719. Return Values for Datasource::close()

Return Type

Description

Integer

0 for success, -1 for not open.


4.16.9. Datasource::commit()

Synopsis

Commits the current transaction and releases the transaction lock.

Usage
Datasource::commit()
Example
$db.commit();

Table 4.720. Arguments for Datasource::commit()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.721. Return Values for Datasource::commit()

Return Type

Description

Integer

0 for success, -1 for not open.


Table 4.722. Exceptions Thrown by Datasource::commit()

err

desc

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock.

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.10. Datasource::rollback()

Synopsis

Rolls back the current transaction and releases the transaction lock.

Usage
Datasource::rollback()
Example
$db.rollback();

Table 4.723. Arguments for Datasource::rollback()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.724. Return Values for Datasource::rollback()

Return Type

Description

Integer

0 for success, -1 for not open.


Table 4.725. Exceptions Thrown by Datasource::rollback()

err

desc

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock.

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.11. Datasource::setAutoCommit()

Synopsis

Turns autocommit on or off for this object.

Usage
Datasource::setAutoCommit(status)
Example
$db.setAutoCommit(False);

Table 4.726. Arguments for Datasource::setAutoCommit()

Argument

Type

Description

status

Boolean

True to turn on autocommit (a commit will be executed after every Datasource::exec()), False to turn off autocommit (commits must be manually triggered).


Table 4.727. Return Values for Datasource::setAutoCommit()

Return Type

Description

n/a

This method does not return any value.


4.16.12. Datasource::exec()

Synopsis

Grabs the transaction lock (if autocommit is disabled) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values).

Usage
Datasource::exec(sql_command, [arg1, ...])
Example
$rows = $db.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);

Table 4.728. Arguments for Datasource::exec()

Argument

Type

Description

sql_command

String

The SQL command to execute on the server.

[arg1, ...]

Any

Include any values to be bound (using %v in the command string) or placeholder specifications (using :<key_name> in the command string) in order after the command string.


Table 4.729. Return Values for Datasource::exec()

Return Type

Description

Integer or Hash

For commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, a row count is returned.


Table 4.730. Exceptions Thrown by Datasource::exec()

err

desc

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock.

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.13. Datasource::vexec()

Synopsis

Same as the Datasource::exec() method, except this method takes a single argument after the SQL command giving the list of bind parameters.

Usage
Datasource::vexec(sql_command, [list])
Example
$rows = $db.vexec("insert into example_table value (%v, %v, %v)", $arg_list);

Table 4.731. Arguments for Datasource::vexec()

Argument

Type

Description

sql_command

String

The SQL command to execute on the server.

[list]

List

Include any values to be bound (using %v in the command string) or placeholder specifications (using :<key_name> in the command string) in a single list in order after the command string.


Table 4.732. Return Values for Datasource::vexec()

Return Type

Description

Integer or Hash

For commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, a row count is returned.


Table 4.733. Exceptions Thrown by Datasource::vexec()

err

desc

TRANSACTION-LOCK-TIMEOUT

Timeout trying to acquire the transaction lock.

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.14. Datasource::select()

Synopsis

Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (rows). This format is suitable for use with context Statements, for easy iteration and processing of query results. Additionally, this format is more efficient format than that returned by the Datasource::selectRows() method, because the column names are not repeated for each row returned. Therefore, for retrieving anything greater than small amounts of data, it is recommended to use this method instead of Datasource::selectRows().

Usage
Datasource::select(select_statement, [arg1, ...])
Example
# bind a string and a date/time value by value in a query
$query = $db.select("select * from table where varchar_column = %v and timestamp_column > %v", $string, 2007-10-11T15:31:26.289);

Table 4.734. Arguments for Datasource::select()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.735. Return Values for Datasource::select()

Return Type

Description

Hash

Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data).


Table 4.736. Exceptions Thrown by Datasource::select()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.15. Datasource::vselect()

Synopsis

Same as the Datasource::select() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.

Usage
Datasource::vselect(select_statement, [list])
Example
$query = $db.vselect("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.737. Arguments for Datasource::vselect()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.738. Return Values for Datasource::vselect()

Return Type

Description

Hash

Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data).


Table 4.739. Exceptions Thrown by Datasource::vselect()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.16. Datasource::selectRow()

Synopsis

Executes an SQL select statement on the server and returns the first row as a hash (the column values). If more than one row is returned, then all but the first row are discarded. For a similar method taking a list for all bind arguments, see Datasource::vselectRow().

This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.

Usage
Datasource::selectRow(select_statement, [arg1, ...])
Example
$list = $db.selectRow("select * from example_table");

Table 4.740. Arguments for Datasource::selectRow()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.741. Return Values for Datasource::selectRow()

Return Type

Description

Hash or NOTHING

Returns a hash (column values) of the first row, NOTHING if no rows are returned.


Table 4.742. Exceptions Thrown by Datasource::selectRow()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.17. Datasource::vselectRow()

Synopsis

Same as the Datasource::selectRow() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.

Usage
Datasource::vselectRow(select_statement, [list])
Example
$list = $db.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.743. Arguments for Datasource::vselectRow()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[list]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.744. Return Values for Datasource::vselectRow()

Return Type

Description

Hash or NOTHING

Returns a hash of the first row (column values). If no rows are returned by the query, then NOTHING is returned.


Table 4.745. Exceptions Thrown by Datasource::vselectRow()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.18. Datasource::selectRows()

Synopsis

Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values). This format is not as efficient as that returned by the Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::select().

This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.

Usage
Datasource::selectRows(select_statement, [arg1, ...])
Example
$list = $db.selectRows("select * from example_table");

Table 4.746. Arguments for Datasource::selectRows()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[arg1, ...]

Any

Arguments to bind by value in %v positions in the SQL string.


Table 4.747. Return Values for Datasource::selectRows()

Return Type

Description

List

Returns a list (the rows returned) of hashes (column values).


Table 4.748. Exceptions Thrown by Datasource::selectRows()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.19. Datasource::vselectRows()

Synopsis

Same as the Datasource::selectRows() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.

Usage
Datasource::vselectRows(select_statement, [list])
Example
$list = $db.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);

Table 4.749. Arguments for Datasource::vselectRows()

Argument

Type

Description

select_statement

String

SQL select statement to execute on the server.

[list]

List

A list of arguments to bind by value in %v positions in the SQL string.


Table 4.750. Return Values for Datasource::vselectRows()

Return Type

Description

List

Returns a list (the rows returned) of hashes (column values).


Table 4.751. Exceptions Thrown by Datasource::vselectRows()

err

desc

depends on DBI driver

See documentation for the DBI driver for driver-specific exceptions.


4.16.20. Datasource::setTransactionLockTimeout()

Synopsis

Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds).

Usage
Datasource::setTransactionLockTimeout(timeout_ms)
Example
$db.setTransactionLockTimeout(5m); # transaction lock timeout set to 5 minutes

Table 4.752. Arguments for Datasource::setTransactionLockTimeout()

Argument

Type

Description

timeout_ms

Integer

The timeout value to set in seconds. For no timeout, set to 0. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms for 2.5 seconds).


Table 4.753. Return Values for Datasource::setTransactionLockTimeout()

Return Type

Description

n/a

This method does not return any value.


4.16.21. Datasource::getTransactionLockTimeout()

Synopsis

Retrieves the transaction lock timeout value as an integer in milliseconds.

Usage
Datasource::getTransactionLockTimeout()
Example
$int = $db.getTransactionLockTimeout();

Table 4.754. Arguments for Datasource::getTransactionLockTimeout()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.755. Return Values for Datasource::getTransactionLockTimeout()

Return Type

Description

Integer

The transaction lock timeout value in milliseconds.


4.16.22. Datasource::setUserName()

Synopsis

Sets the username to use for the connection. Invalid usernames will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setUserName(username)
Example
$db.setUserName("user");

Table 4.756. Arguments for Datasource::setUserName()

Argument

Type

Description

username

String

The username to be used for the connection.


Table 4.757. Return Values for Datasource::setUserName()

Return Type

Description

n/a

This method does not return any value.


4.16.23. Datasource::getUserName()

Synopsis

Retrieves the username parameter for connections to the database.

Usage
Datasource::getUserName()
Example
$str = $db.getUserName();

Table 4.758. Arguments for Datasource::getUserName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.759. Return Values for Datasource::getUserName()

Return Type

Description

String

The username connection parameter.


4.16.24. Datasource::setPassword()

Synopsis

Sets the password to use for the connection. Invalid passwords will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setPassword()
Example
$db.setPassword("pass");

Table 4.760. Arguments for Datasource::setPassword()

Argument

Type

Description

password

String

The password name to be used for the connection.


Table 4.761. Return Values for Datasource::setPassword()

Return Type

Description

n/a

This method does not return any value.


4.16.25. Datasource::getPassword()

Synopsis

Retrieves the password connection parameter.

Usage
Datasource::getPassword()
Example
$str = $db.getPassword();

Table 4.762. Arguments for Datasource::getPassword()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.763. Return Values for Datasource::getPassword()

Return Type

Description

String

Retrieves the password connection parameter.


4.16.26. Datasource::setDBName()

Synopsis

Sets the database name to use for the connection. Invalid database names will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setDBName(dbname)
Example
$db.setDBName("database");

Table 4.764. Arguments for Datasource::setDBName()

Argument

Type

Description

dbname

String

The database name to be used for the connection.


Table 4.765. Return Values for Datasource::setDBName()

Return Type

Description

n/a

This method does not return any value.


4.16.27. Datasource::getDBName()

Synopsis

Retrieves the dbname connection parameter.

Usage
Datasource::getDBName()
Example
$str = $db.getDBName();

Table 4.766. Arguments for Datasource::getDBName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.767. Return Values for Datasource::getDBName()

Return Type

Description

String

Retrieves the password connection parameter.


4.16.28. Datasource::setDBCharset()

Synopsis

Sets the database-specific character encoding to use for the connection. Invalid character encoding names will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setDBCharset(encoding)
Example
$db.setDBCharset("ALU32UTF8"); # Oracle UTF-8 encoding equivalent

Table 4.768. Arguments for Datasource::setDBCharset()

Argument

Type

Description

db_encoding_name

String

The database-specific name for the encoding to be used for the connection.


Table 4.769. Return Values for Datasource::setDBCharset()

Return Type

Description

n/a

This method does not return any value.


4.16.29. Datasource::setHostName()

Synopsis

Sets the hostname to use for the connection (for DBI drivers that support this parameter, such as the mysql and pgsql, for example). Invalid hostnames will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setHostName(hostname)
Example
$db.setHostName("localhost");

Table 4.770. Arguments for Datasource::setHostName()

Argument

Type

Description

hostname

String

The hostname to be used for the connection.


Table 4.771. Return Values for Datasource::setHostName()

Return Type

Description

n/a

This method does not return any value.


4.16.30. Datasource::setPort()

Synopsis

Sets the port number to use for the connection (for DBI drivers that support this parameter, such as the mysql, pgsql, and oracle drivers, for example). Invalid port numbers will cause an exception to be thrown when the connection is opened.

Usage
Datasource::setPort(port)
Example
$db.setPort(5432);

Table 4.772. Arguments for Datasource::setPort()

Argument

Type

Description

port

Integer

The port number to be used for the connection.


Table 4.773. Return Values for Datasource::setPort()

Return Type

Description

n/a

This method does not return any value.


4.16.31. Datasource::getDBCharset()

Synopsis

Retrieves the database-specific charset set encoding for the current connection.

Usage
Datasource::getDBCharset()
Example
$str = $db.getDBCharset();

Table 4.774. Arguments for Datasource::getDBCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.775. Return Values for Datasource::getDBCharset()

Return Type

Description

String

Retrieves the database-specific charset set encoding for the current connection.


4.16.32. Datasource::getOSCharset()

Synopsis

Retrieves the Qore charset set encoding for the current connection.

Usage
Datasource::getOSCharset()
Example
$str = $db.getOSCharset();

Table 4.776. Arguments for Datasource::getOSCharset()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.777. Return Values for Datasource::getOSCharset()

Return Type

Description

String

Retrieves the Qore charset set encoding for the current connection.


4.16.33. Datasource::getHostName()

Synopsis

Retrieves the hostname connection parameter.

Usage
Datasource::getHostName()
Example
$str = $db.getHostName();

Table 4.778. Arguments for Datasource::getHostName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.779. Return Values for Datasource::getHostName()

Return Type

Description

String

Retrieves the hostname connection parameter.


4.16.34. Datasource::getPort()

Synopsis

Retrieves the port connection parameter.

Usage
Datasource::getPort()
Example
$port = $db.getPort();

Table 4.780. Arguments for Datasource::getPort()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.781. Return Values for Datasource::getPort()

Return Type

Description

Integer or NOTHING

Retrieves the port connection parameter or no value if no port is set.


4.16.35. Datasource::getDriverName()

Synopsis

Returns the name of the DBI driver used for this object.

Usage
Datasource::getDriverName()
Example
$name = $db.getDriverName();

Table 4.782. Arguments for Datasource::getDriverName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.783. Return Values for Datasource::getDriverName()

Return Type

Description

String

The name of the database driver used for this object.


4.16.36. Datasource::getServerVersion()

Synopsis

Retrieves the driver-specific server version information for the current connection.

Usage
Datasource::getServerVersion()
Example
$data = $db.getServerVersion();

Table 4.784. Arguments for Datasource::getServerVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.785. Return Values for Datasource::getServerVersion()

Return Type

Description

Driver-Specific

See the documentation for the DBI driver used for the connection.


4.16.37. Datasource::getClientVersion()

Synopsis

Retrieves the driver-specific client library version information. Not implemented for all drivers.

Usage
Datasource::getClientVersion()
Example
$data = $db.getClientVersion();

Table 4.786. Arguments for Datasource::getClientVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.787. Return Values for Datasource::getClientVersion()

Return Type

Description

Driver-Specific

See the documentation for the DBI driver used for the connection.