[ library(dbi) | Reference Manual | Alphabetic Index ]

# session_start(++Login, ++Password, ++Options, -Session)

starts a new session for the DBMS

Login
  DBMS login: ID or ID@Host. (ID,Host: string or atom)
Password
  Password (string or atom)
Options
  Options (list or nil)
Session
  Session handle

## Description

Starts a new session with the DBMS. A new connection with the DBMS server is established, with the supplied DBMS user ID. Optionally, a host could be supplied, if the server is located on a remote machine. The host could be either the machine name, or an IP address. A session handle for this new connection is returned by the predicate.

The session is closed automatically if the program backtracks or aborts back beyond this call.

Options is a (possibly empty) list of `Option:Value` pairs, specifying any options for this session. The following options are supported:

`dbname`
  Specifies the name of the database to use. Value can be a string or an atom. The same effect can also be achieved by issuing the SQL statement `USE ...` (where ... is the dbname).

`storage`
  (MySQL specific) specifies the default storage model to use for the tables. Value can be either the string/atom `transactional` or `non-transactional`. For transactional tables, changes are local until they are committed. Uncommitted changes can be rollback. For non-transactional tables, changes are global. InnoDB (with autocommit turned off) is the storage engine used for transactional, and MyISAM is the storage engine used for non-transactional. See the MySQL manual for details on storage engines and their effect on tables.

### Exceptions

(5) type error
  Login, Password or Options not of the correct type.
(6) out of range
  Invalid option specification in Options.
(dbi_bad_field)
  Problems with Option's argument.
(dbi_error)
  Problems connecting to DBMS server.

## Examples

         % connecting to a database server running on the local machine, as
         % database user sqluser with password password
         session_start("sqluser", "password", [], S).

         % connecting to a database server running on machine my.sql.host,
         % as database user sqluser with password password, and selecting
         % to use the database mydb
         session_start(sqluser@my.sql.host, password, [dbame:"mydb"], S).

## See Also

session_close / 1