Warning, /sdk/codevis/thirdparty/soci/docs/languages/ada/reference.md is written in an unsupported language. File is not indexed.
0001 # Ada API Reference 0002 0003 The SOCI-Ada library is entirely implemented as a single package named `SOCI`. Additional child packages contain single procedures for static registration of backends - these child packages are not necessary for typical use, but can be useful to force static linking of backend code. 0004 0005 The following describes all publicly visible elements of this package: 0006 0007 ```ada 0008 -- 0009 -- General exception related to database and library usage. 0010 -- 0011 0012 Database_Error : exception; 0013 ``` 0014 0015 Each problem related to the interaction with the database or to the incorrect usage of the library itself is signalled by raising this exception. Each occurrence of this exception has some human-readable error message that can be obtained by a call to `Ada.Exceptions.Exception_Message`. 0016 0017 ```ada 0018 -- 0019 -- Session. 0020 -- 0021 0022 type Session is tagged limited private; 0023 0024 not overriding 0025 function Make_Session (Connection_String : in String) return Session; 0026 0027 not overriding 0028 procedure Open (This : in out Session; Connection_String : in String); 0029 0030 not overriding 0031 procedure Close (This : in out Session); 0032 0033 not overriding 0034 function Is_Open (This : in Session) return Boolean; 0035 ``` 0036 0037 The `Session` object can exist in two states: "connected" (or "open") and "disconnected". It can be created as connected at initialization time with a call to the constructor function `Make_Session` or left default-initialized in the disconnected state and later changed to connected with `Open` (the latter option is the only that is available in the Ada 95 version of the library). `Session` objects can be also associated with the connection pool, see below. 0038 0039 The `Connection_String` should have the form `"backendname://parameters"`, where `backendname` is used to construct the name of the dynamically loadable library that will be used to provide specific database services. Backends included in the current distribution of the main SOCI library are: 0040 0041 * `oracle` (implemented as `libsoci_oracle.so` or `libsoci_oracle.dll`) 0042 * `postgresql` (implemented as `libsoci_postgresql.so` or `libsoci_postgresql.dll`) 0043 * `mysql` (implemented as `libsoci_mysql.so` or `libsoci_mysql.dll`) 0044 0045 Other backends can be added to the library in the future or by the user himself, please see the documentation of the main SOCI library for details. 0046 0047 The `parameters` component of the `Connection_String` depends on the given backend, please see the documentation of the main SOCI project for the meaning and recognized options. The web pages related to the backends above are: 0048 0049 * [Oracle](../../backends/oracle.md) 0050 * [PostgreSQL](../../backends/postgresql.md) 0051 * [MySQL](../../backends/mysql.md) 0052 0053 The `Open` operation can be called only in the disconnected state (which changes the state of `Session` object to connected). The `Close` operation can be called in any state (provided that the session is not associated with the connection pool, see below) and after that the `Session` is in the disconnected state. 0054 0055 `Session` objects are closed automatically as part of their finalization. If the `Session` object is associated with the connection pool, the finalizer detaches from the pool without closing the connection. 0056 0057 ```ada 0058 -- Transaction management. 0059 0060 not overriding 0061 procedure Start (This : in Session); 0062 0063 not overriding 0064 procedure Commit (This : in Session); 0065 0066 not overriding 0067 procedure Rollback (This : in Session); 0068 ``` 0069 0070 These operations handle transactions. The exact meaning of transactions and whether transactions are automatic for some kinds of statements (and which ones) depend on the target database. 0071 0072 ```ada 0073 -- Immediate query execution. 0074 not overriding 0075 procedure Execute (This : in Session; Query : in String); 0076 ``` 0077 0078 This operation allows to create implicit statement, prepare it for the given `Query` and execute it. 0079 0080 ```ada 0081 -- 0082 -- Connection pool management. 0083 -- 0084 0085 type Connection_Pool (Size : Positive) is tagged limited private; 0086 0087 not overriding 0088 procedure Open 0089 (This : in out Connection_Pool; 0090 Position : in Positive; 0091 Connection_String : in String); 0092 0093 not overriding 0094 procedure Close (This : in out Connection_Pool; Position : in Positive); 0095 0096 not overriding 0097 procedure Lease (This : in out Connection_Pool; S : in out Session'Class); 0098 ``` 0099 0100 The `Connection_Pool` encapsulates a fixed-size collection of sessions. Individual sessions are indexed from `1` to `Size` (provided as discriminant) and can be `Open`ed and `Close`d explicitly. Each connection in the pool can be created with different `Connection_String`, if needed. 0101 0102 The `Lease` operation allows to associate a given `Session` object (that has to be in the disconnected state itself) with one connection from the pool. The pool guarantees that at most one task can lease a given connection from the pool. If there are no free connections in the pool, the `Lease` operation will block waiting until some connection is freed. 0103 0104 The `Session` object that is associated with a connection from the pool automatically gives it back to pool as part of the `Session`'s finalizer. There is no other way to "detach" from the pool. 0105 0106 Note: 0107 0108 It is assumed that the lifetime of `Connection_Pool` encloses the lifetimes of all `Session` objects that are leased from it. There is no particular protection against it and it is possible to construct a code example with allocators that create partially overlapping `Connection_Pool` and `Session`, but this is considered obscure and not representative to the actual use scenarios. To avoid any potential problems, create `Connection_Pool` in the scope that encloses the scopes of leased `Session`s. 0109 0110 ```ada 0111 -- 0112 -- Statement. 0113 -- 0114 0115 type Statement (<>) is tagged limited private; 0116 0117 type Data_State is (Data_Null, Data_Not_Null); 0118 0119 type Into_Position is private; 0120 0121 type Vector_Index is new Natural; 0122 ``` 0123 0124 The `Statement` type and supporting types. `Data_State` is used to indicate null values in the database sense - each value of into or use elements has a state from this type. 0125 0126 ```ada 0127 -- Statement preparation and execution. 0128 0129 not overriding 0130 procedure Prepare (This : in Statement; Query : in String); 0131 0132 not overriding 0133 procedure Execute 0134 (This : in Statement; 0135 With_Data_Exchange : in Boolean := False); 0136 0137 not overriding 0138 function Execute 0139 (This : in Statement; 0140 With_Data_Exchange : in Boolean := False) return Boolean; 0141 0142 not overriding 0143 function Fetch (This : in Statement) return Boolean; 0144 0145 not overriding 0146 function Got_Data (This : in Statement) return Boolean; 0147 ``` 0148 0149 The `Prepare` operation needs to be called before any other operation in the above group and it prepares the execution for the given `Query`. No into and use elements can be created after this operation is called. 0150 0151 The `Execute` operations cause the statement to execute, which might be combined with data exchange if requested. The function version of this operation returns `True` if some data has been returned back from the database server. 0152 0153 The `Fetch` function is used to transfer next portion of data (a single row or a whole bunch) from the database server and returns `True` if some data has been fetched. If this function returns `False` it means that no new data will be ever fetched for this statement and indicates the end-of-row condition. 0154 0155 The `Got_Data` function returns `True` if the last execution or fetch resulted in some data being transmitted from the database server. 0156 0157 ```ada 0158 -- 0159 -- Data items handling. 0160 -- 0161 0162 -- Database-specific types. 0163 -- These types are most likely identical to standard Integer, 0164 -- Long_Long_Integer and Long_Float, but are defined distinctly 0165 -- to avoid interfacing problems with other compilers. 0166 0167 type DB_Integer is new Interfaces.C.int; 0168 type DB_Long_Long_Integer is new Interfaces.Integer_64; 0169 type DB_Long_Float is new Interfaces.C.double; 0170 ``` 0171 0172 The data types used for interaction with the database are: 0173 0174 * `String` 0175 * `DB_Integer`, defined above 0176 * `DB_Long_Long_Integer`, defined above 0177 * `DB_Long_Float`, defined above 0178 * `Ada.Calendar.Time` 0179 0180 ```ada 0181 -- Creation of single into elements. 0182 0183 not overriding 0184 function Into_String (This : in Statement) return Into_Position; 0185 0186 not overriding 0187 function Into_Integer (This : in Statement) return Into_Position; 0188 0189 not overriding 0190 function Into_Long_Long_Integer (This : in Statement) return Into_Position; 0191 0192 not overriding 0193 function Into_Long_Float (This : in Statement) return Into_Position; 0194 0195 not overriding 0196 function Into_Time (This : in Statement) return Into_Position; 0197 ``` 0198 0199 These functions instruct the library to create internal simple into elements of the relevant type. They return the position of the into element, which can be later used to identify it. 0200 0201 Note: Simple into elements cannot be created together with vector into elements for the same statement. 0202 0203 Note: Simple into elements cannot be created together with vector into elements for the same statement. 0204 0205 ```ada 0206 -- Inspection of single into elements. 0207 0208 not overriding 0209 function Get_Into_State 0210 (This : in Statement; 0211 Position : in Into_Position) 0212 return Data_State; 0213 0214 not overriding 0215 function Get_Into_String 0216 (This : in Statement; 0217 Position : in Into_Position) 0218 return String; 0219 0220 not overriding 0221 function Get_Into_Integer 0222 (This : in Statement; 0223 Position : in Into_Position) 0224 return DB_Integer; 0225 0226 not overriding 0227 function Get_Into_Long_Long_Integer 0228 (This : in Statement; 0229 Position : in Into_Position) 0230 return DB_Long_Long_Integer; 0231 0232 not overriding 0233 function Get_Into_Long_Float 0234 (This : in Statement; 0235 Position : in Into_Position) 0236 return DB_Long_Float; 0237 0238 not overriding 0239 function Get_Into_Time 0240 (This : in Statement; 0241 Position : in Into_Position) 0242 return Ada.Calendar.Time; 0243 ``` 0244 0245 These functions allow to inspect the state and value of the simple into element identified by its position. If the state of the given element is `Data_Null`, the data-reading functions raise exceptions for that element. 0246 0247 ```ada 0248 -- Inspection of vector into elements. 0249 0250 not overriding 0251 function Get_Into_Vectors_Size (This : in Statement) return Natural; 0252 0253 not overriding 0254 function Into_Vectors_First_Index (This : in Statement) return Vector_Index; 0255 0256 not overriding 0257 function Into_Vectors_Last_Index (This : in Statement) return Vector_Index; 0258 0259 not overriding 0260 procedure Into_Vectors_Resize (This : in Statement; New_Size : in Natural); 0261 ``` 0262 0263 The `Get_Into_Vectors_Size` returns the number of entries in any of the vector into elements for the given statement. 0264 0265 The `Into_Vectors_First_Index` returns the lowest index value for vector into elements (which is always `0`, even if the vectors are empty). The `Into_Vectors_Last_Index` returns the last index of into vectors, and raises the `CONSTRAINT_ERROR` exception if the vectors are empty. 0266 0267 The `Into_Vectors_Resize` procedure allows to change the size of all use vectors for the given statement. 0268 0269 ```ada 0270 not overriding 0271 function Get_Into_Vector_State 0272 (This : in Statement; 0273 Position : in Into_Position; 0274 Index : in Vector_Index) 0275 return Data_State; 0276 0277 not overriding 0278 function Get_Into_Vector_String 0279 (This : in Statement; 0280 Position : in Into_Position; 0281 Index : in Vector_Index) 0282 return String; 0283 0284 not overriding 0285 function Get_Into_Vector_Integer 0286 (This : in Statement; 0287 Position : in Into_Position; 0288 Index : in Vector_Index) 0289 return DB_Integer; 0290 0291 not overriding 0292 function Get_Into_Vector_Long_Long_Integer 0293 (This : in Statement; 0294 Position : in Into_Position; 0295 Index : in Vector_Index) 0296 return DB_Long_Long_Integer; 0297 0298 not overriding 0299 function Get_Into_Vector_Long_Float 0300 (This : in Statement; 0301 Position : in Into_Position; 0302 Index : in Vector_Index) 0303 return DB_Long_Float; 0304 0305 not overriding 0306 function Get_Into_Vector_Time 0307 (This : in Statement; 0308 Position : in Into_Position; 0309 Index : in Vector_Index) 0310 return Ada.Calendar.Time; 0311 ``` 0312 0313 These functions allow to inspect the state and value of the vector use element identified by its position and index. If the state of the given element is `Data_Null`, the data-reading functions raise exceptions for that element. 0314 0315 ```ada 0316 -- Creation of single use elements. 0317 0318 not overriding 0319 procedure Use_String (This : in Statement; Name : in String); 0320 0321 not overriding 0322 procedure Use_Integer (This : in Statement; Name : in String); 0323 0324 not overriding 0325 procedure Use_Long_Long_Integer (This : in Statement; Name : in String); 0326 0327 not overriding 0328 procedure Use_Long_Float (This : in Statement; Name : in String); 0329 0330 not overriding 0331 procedure Use_Time (This : in Statement; Name : in String); 0332 ``` 0333 0334 These functions instruct the library to create internal simple use elements of the relevant type, identified by the given `Name`. 0335 0336 Note: 0337 0338 * Simple use elements cannot be created together with vector use elements for the same statement. 0339 * Vector use elements cannot be created together with any into elements for the same statement. 0340 0341 ```ada 0342 -- Creation of vector use elements. 0343 0344 not overriding 0345 procedure Use_Vector_String (This : in Statement; Name : in String); 0346 0347 not overriding 0348 procedure Use_Vector_Integer (This : in Statement; Name : in String); 0349 0350 not overriding 0351 procedure Use_Vector_Long_Long_Integer (This : in Statement; Name : in String); 0352 0353 not overriding 0354 procedure Use_Vector_Long_Float (This : in Statement; Name : in String); 0355 0356 not overriding 0357 procedure Use_Vector_Time (This : in Statement; Name : in String); 0358 ``` 0359 0360 These functions instruct the library to create internal vector use elements of the relevant type, identified by the given `Name`. 0361 0362 Note: 0363 0364 * Simple use elements cannot be created together with vector use elements for the same statement. 0365 * Vector use elements cannot be created together with any into elements for the same statement. 0366 0367 ```ada 0368 -- Modifiers for single use elements. 0369 0370 not overriding 0371 procedure Set_Use_State 0372 (This : in Statement; 0373 Name : in String; 0374 State : in Data_State); 0375 0376 not overriding 0377 procedure Set_Use_String 0378 (This : in Statement; 0379 Name : in String; 0380 Value : in String); 0381 0382 not overriding 0383 procedure Set_Use_Integer 0384 (This : in Statement; 0385 Name : in String; 0386 Value : in DB_Integer); 0387 0388 not overriding 0389 procedure Set_Use_Long_Long_Integer 0390 (This : in Statement; 0391 Name : in String; 0392 Value : in DB_Long_Long_Integer); 0393 0394 not overriding 0395 procedure Set_Use_Long_Float 0396 (This : in Statement; 0397 Name : in String; 0398 Value : in DB_Long_Float); 0399 0400 not overriding 0401 procedure Set_Use_Time 0402 (This : in Statement; 0403 Name : in String; 0404 Value : in Ada.Calendar.Time); 0405 ``` 0406 0407 These operations allow to modify the state and value of simple use elements. Setting the value of use element automatically sets its state to `Data_Not_Null`. 0408 0409 ```ada 0410 -- Modifiers for vector use elements. 0411 0412 not overriding 0413 function Get_Use_Vectors_Size (This : in Statement) return Natural; 0414 0415 not overriding 0416 function Use_Vectors_First_Index (This : in Statement) return Vector_Index; 0417 0418 not overriding 0419 function Use_Vectors_Last_Index (This : in Statement) return Vector_Index; 0420 0421 not overriding 0422 procedure Use_Vectors_Resize (This : in Statement; New_Size : in Natural); 0423 ``` 0424 0425 The `Get_Use_Vectors_Size` returns the number of entries in any of the vector use elements for the given statement. 0426 0427 The `Use_Vectors_First_Index` returns the lowest index value for vector use elements (which is always `0`, even if the vectors are empty). The `Use_Vectors_Last_Index` returns the last index of use vectors, and raises the `CONSTRAINT_ERROR` exception if the vectors are empty. 0428 0429 The `Use_Vectors_Resize` procedure allows to change the size of all use vectors for the given statement. 0430 0431 ```ada 0432 not overriding 0433 procedure Set_Use_Vector_State 0434 (This : in Statement; 0435 Name : in String; 0436 Index : in Vector_Index; 0437 State : in Data_State); 0438 0439 not overriding 0440 procedure Set_Use_Vector_String 0441 (This : in Statement; 0442 Name : in String; 0443 Index : in Vector_Index; 0444 Value : in String); 0445 0446 not overriding 0447 procedure Set_Use_Vector_Integer 0448 (This : in Statement; 0449 Name : in String; 0450 Index : in Vector_Index; 0451 Value : in DB_Integer); 0452 0453 not overriding 0454 procedure Set_Use_Vector_Long_Long_Integer 0455 (This : in Statement; 0456 Name : in String; 0457 Index : in Vector_Index; 0458 Value : in DB_Long_Long_Integer); 0459 0460 not overriding 0461 procedure Set_Use_Vector_Long_Float 0462 (This : in Statement; 0463 Name : in String; 0464 Index : in Vector_Index; 0465 Value : in DB_Long_Float); 0466 0467 not overriding 0468 procedure Set_Use_Vector_Time 0469 (This : in Statement; 0470 Name : in String; 0471 Index : in Vector_Index; 0472 Value : in Ada.Calendar.Time); 0473 ``` 0474 0475 These operations allow to modify the state and value of vector use elements. Setting the value of use element automatically sets its state to `Data_Not_Null`. 0476 0477 ```ada 0478 -- Inspection of single use elements. 0479 -- 0480 -- Note: Use elements can be modified by the database if they 0481 -- are bound to out and inout parameters of stored procedures 0482 -- (although this is not supported by all database backends). 0483 -- This feature is available only for single use elements. 0484 0485 not overriding 0486 function Get_Use_State 0487 (This : in Statement; 0488 Name : in String) 0489 return Data_State; 0490 0491 not overriding 0492 function Get_Use_String 0493 (This : in Statement; 0494 Name : in String) 0495 return String; 0496 0497 not overriding 0498 function Get_Use_Integer 0499 (This : in Statement; 0500 Name : in String) 0501 return DB_Integer; 0502 0503 not overriding 0504 function Get_Use_Long_Long_Integer 0505 (This : in Statement; 0506 Name : in String) 0507 return DB_Long_Long_Integer; 0508 0509 not overriding 0510 function Get_Use_Long_Float 0511 (This : in Statement; 0512 Name : in String) 0513 return DB_Long_Float; 0514 0515 not overriding 0516 function Get_Use_Time 0517 (This : in Statement; 0518 Name : in String) 0519 return Ada.Calendar.Time; 0520 ``` 0521 0522 These functions allow to inspect the state and value of the simple use element identified by its name. If the state of the given element is `Data_Null`, the data-reading functions raise exceptions for that element.