languages/ada/concepts.md

0001 # Ada Concepts
0002
0003 The SOCI-Ada library borrows its concepts and naming from the main SOCI project. They are shortly explained here in the bottom-up fashion.
0004
0005 One of the main properties of the library is that the data objects which are bound for transfer to and from the database server are managed by the library itself and are not directly visible from the user code. This ensures that no aliasing of objects occurs between Ada and underlying C++ code, which makes the inter-language interface easier and more resilient to the differences in how compilers handle the linkage. As a direct result of this design choice, users of SOCI-Ada need to instruct the library to internally create all objects that will be subject to data transfer.
0006
0007 There are two kinds of objects that can be managed by the SOCI-Ada library:
0008
0009 * *Into elements*, which are data objects that are transferred from the database to the user program as a result of executing a query. There are single into elements for binding single rows of results and vector into elements for binding whole bunches of data corresponding to whole result sets or their subranges. The into elements are identified by their *position*.
0010
0011 * *Use elements*, which are data objects that are transferred from the user program to the database as parameters of the query (and, if supported by the target database, that can be modified by the database server and transferred back to the user program). There are single use elements for binding parameters of single-row queries and vector use elements for binding whole bunches of data for transfer. The use elements are identified by their *name*.
0012
0013 The user program can read the current value of into and use elements and assign new values to use elements. Elements are strongly typed and the following types are currently supported:
0014
0015 * `String`
0016 * `SOCI.DB_Integer`, which is defined by the library in terms of `Interfaces.C.int`
0017 * `SOCI.DB_Long_Long_Integer`, which is defined in terms of `Interfaces.Integer_64`
0018 * `SOCI.DB_Long_Float`, which is defined in terms of `Interfaces.C.double`
0019 * `Ada.Calendar.Time`
0020
0021 Both into and use elements are managed for a single *statement*, which can be prepared once and executed once or many times, with data transfer handled during execution or fetch phase.
0022
0023 Statements can be managed explicitly, which is required if they are to be used repeteadly or when data transfer is needed or implicitly, which is a shorthand notation that is particularly useful with simple queries or DDL commands.
0024
0025 All statements are handled within the context of some *session*, which also supports *transactions*.
0026
0027 Sessions can be managed in isolation or as a group called *connection pool*, which helps to decouple tasking design choices from the concurrency policies at the database connection level. Sessions are *leased* from the pool for some time during which no other task can access them and returned back when no longer needed, where they can be acquired again by other tasks.
0028
0029 All potential problems are signalled via exceptions that have some descriptive message attached to them.