1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
|
<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>Client API - SOCI (4.1.2)</title>
<link href="../../css/bootstrap.min.css" rel="stylesheet">
<link href="../../css/fontawesome.min.css" rel="stylesheet">
<link href="../../css/brands.min.css" rel="stylesheet">
<link href="../../css/solid.min.css" rel="stylesheet">
<link href="../../css/v4-font-face.min.css" rel="stylesheet">
<link href="../../css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="../..">SOCI (4.1.2)</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item">
<a href="../.." class="nav-link">Home</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Overview</a>
<ul class="dropdown-menu">
<li>
<a href="../../quickstart/" class="dropdown-item">Getting Started</a>
</li>
<li>
<a href="../../installation/" class="dropdown-item">Installation</a>
</li>
<li>
<a href="../../structure/" class="dropdown-item">Library Structure</a>
</li>
<li>
<a href="../../license/" class="dropdown-item">License</a>
</li>
<li>
<a href="../../faq/" class="dropdown-item">FAQ</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">User Guide</a>
<ul class="dropdown-menu">
<li>
<a href="../../connections/" class="dropdown-item">Connections</a>
</li>
<li>
<a href="../../queries/" class="dropdown-item">Queries</a>
</li>
<li>
<a href="../../binding/" class="dropdown-item">Data Binding</a>
</li>
<li>
<a href="../../indicators/" class="dropdown-item">Data Indicators</a>
</li>
<li>
<a href="../../types/" class="dropdown-item">Data Types</a>
</li>
<li>
<a href="../../lobs/" class="dropdown-item">LOBs</a>
</li>
<li>
<a href="../../statements/" class="dropdown-item">Statements</a>
</li>
<li>
<a href="../../transactions/" class="dropdown-item">Transactions</a>
</li>
<li>
<a href="../../procedures/" class="dropdown-item">Procedures</a>
</li>
<li>
<a href="../../errors/" class="dropdown-item">Errors</a>
</li>
<li>
<a href="../../logging/" class="dropdown-item">Logging</a>
</li>
<li>
<a href="../../interfaces/" class="dropdown-item">Interfaces</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Backends</a>
<ul class="dropdown-menu">
<li>
<a href="../../backends/" class="dropdown-item">Features</a>
</li>
<li>
<a href="../../backends/db2/" class="dropdown-item">DB2</a>
</li>
<li>
<a href="../../backends/firebird/" class="dropdown-item">Firebird</a>
</li>
<li>
<a href="../../backends/mysql/" class="dropdown-item">MySQL</a>
</li>
<li>
<a href="../../backends/odbc/" class="dropdown-item">ODBC</a>
</li>
<li>
<a href="../../backends/oracle/" class="dropdown-item">Oracle</a>
</li>
<li>
<a href="../../backends/postgresql/" class="dropdown-item">PostgreSQL</a>
</li>
<li>
<a href="../../backends/sqlite3/" class="dropdown-item">SQLite3</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" role="button" data-bs-toggle="dropdown" aria-expanded="false">Miscellaneous</a>
<ul class="dropdown-menu">
<li>
<a href="../../beyond/" class="dropdown-item">Beyond SQL</a>
</li>
<li>
<a href="../../multithreading/" class="dropdown-item">Multi-threading</a>
</li>
<li>
<a href="../../boost/" class="dropdown-item">Boost</a>
</li>
<li>
<a href="../../utilities/" class="dropdown-item">Utilities</a>
</li>
<li>
<a href="../../vagrant/" class="dropdown-item">Vagrant</a>
</li>
</ul>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle active" aria-current="page" role="button" data-bs-toggle="dropdown" aria-expanded="false">API</a>
<ul class="dropdown-menu">
<li>
<a href="./" class="dropdown-item active" aria-current="page">Client API</a>
</li>
<li>
<a href="../backend/" class="dropdown-item">Backend API</a>
</li>
<li class="dropdown-submenu">
<a href="#" class="dropdown-item">Ada</a>
<ul class="dropdown-menu">
<li>
<a href="../../languages/ada/" class="dropdown-item">Ada Bindings</a>
</li>
<li>
<a href="../../languages/ada/concepts/" class="dropdown-item">Ada Concepts</a>
</li>
<li>
<a href="../../languages/ada/idioms/" class="dropdown-item">Ada Idioms</a>
</li>
<li>
<a href="../../languages/ada/reference/" class="dropdown-item">Ada API Reference</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../../vagrant/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="../backend/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/SOCI/soci/edit/master/docs/api/client.md" class="nav-link"><i class="fa-brands fa-github"></i> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#api-reference" class="nav-link">API Reference</a>
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="2"><a href="#commonly-used-types" class="nav-link">Commonly used types</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-session" class="nav-link">class session</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-connection_parameters" class="nav-link">class connection_parameters</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-connection_pool" class="nav-link">class connection_pool</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-transaction" class="nav-link">class transaction</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#function-into" class="nav-link">function into</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#function-use" class="nav-link">function use</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-statement" class="nav-link">class statement</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-procedure" class="nav-link">class procedure</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-type_conversion" class="nav-link">class type_conversion</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-row" class="nav-link">class row</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-column_properties" class="nav-link">class column_properties</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-values" class="nav-link">class values</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-blob" class="nav-link">class blob</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-rowid" class="nav-link">class rowid</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#class-backend_factory" class="nav-link">class backend_factory</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#simple-client-interface" class="nav-link">Simple Client Interface</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="api-reference">API Reference</h1>
<p>The core client interface is a set of classes and free functions declared in the <code>soci.h</code> header file.
All names are declared in the <code>soci</code> namespace.</p>
<p>There are also additional names declared in the <code>soci::details</code> namespace, but they are not supposed to be directly used by the users of the library and are therefore not documented here.
When such types are used in the declarations that are part of the "public" interface, they are replaced by "IT", which means "internal type".
Types related to the backend interface are named here.</p>
<h2 id="commonly-used-types">Commonly used types</h2>
<p>The following types are commonly used in the rest of the interface:</p>
<pre><code class="language-cpp">// data types, as seen by the user
enum db_type { db_string, db_wstring, db_date, db_double, db_int8, db_uint8, db_int16, db_uint16, db_int32, db_uint32, db_int64, db_uint64 };
// deprecated data types enum which may be still used but is less precise than db_type
enum data_type { dt_string, dt_date, dt_double, dt_integer, dt_long_long, dt_unsigned_long_long };
// the enum type for indicator variables
enum indicator { i_ok, i_null, i_truncated };
// the type used for reporting exceptions
class soci_error : public std::runtime_error { /* ... */ };
</code></pre>
<p><code>db_type</code> defines the basic SOCI data types. User provided data types need to be associated with one of these basic types.
<code>data_type</code> is deprecated in favor of <code>db_type</code>, please don't use it in the new code any longer.</p>
<p>The <code>indicator</code> type defines the possible states of data.</p>
<p>The <code>soci_error</code> type is used for error reporting.</p>
<h2 id="class-session">class session</h2>
<p>The <code>session</code> class encapsulates the connection to the database.</p>
<pre><code class="language-cpp">class session
{
public:
session();
explicit session(connection_parameters const & parameters);
session(backend_factory const & factory, std::string const & connectString);
session(std::string const & backendName, std::string const & connectString);
explicit session(std::string const & connectString);
explicit session(connection_pool & pool);
~session();
void open(backend_factory const & factory, std::string const & connectString);
void open(std::string const & backendName, std::string const & connectString);
void open(std::string const & connectString);
void close();
void reconnect();
bool is_connected() const;
void begin();
void commit();
void rollback();
*IT* once;
*IT* prepare;
template <typename T> *IT* operator<<(T const & t);
bool got_data() const;
bool get_next_sequence_value(std::string const & sequence, long long & value);
bool get_last_insert_id(std::string const & table, long long & value);
std::ostringstream & get_query_stream();
void set_log_stream(std::ostream * s);
std::ostream * get_log_stream() const;
void log_query(std::string const & query);
void clear_query_parameters();
void add_query_parameter(std::string name, std::string value);
std::string get_last_query() const;
std::string get_last_query_context() const;
void uppercase_column_names(bool forceToUpper);
std::string get_dummy_from_table() const;
std::string get_dummy_from_clause() const;
details::session_backend * get_backend();
std::string get_backend_name() const;
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li>Various constructors. The default one creates the session in the disconnected state. The others expect the backend factory object, or the backend name, or the URL-like composed connection string or the special parameters object containing both the backend and the connection string as well as possibly other connection options. The last constructor creates a session proxy associated with the session that is available in the given pool and releases it back to the pool when its lifetime ends. Example:</li>
</ul>
<pre><code class="language-cpp">session sql(postgresql, "dbname=mydb");
session sql("postgresql", "dbname=mydb");
session sql("postgresql://dbname=mydb");
</code></pre>
<ul>
<li>The constructors that take backend name as string load the shared library (if not yet loaded) with name computed as <code>libsoci_ABC.so</code> (or <code>libsoci_ABC.dll</code> on Windows) where <code>ABC</code> is the given backend name.</li>
<li><code>open</code>, <code>close</code> and <code>reconnect</code> functions for reusing the same session object many times; the <code>reconnect</code> function attempts to establish the connection with the same parameters as most recently used with constructor or <code>open</code>. The arguments for <code>open</code> are treated in the same way as for constructors. <code>is_connected</code> can be used to check if there is an existing usable connection.</li>
<li><code>begin</code>, <code>commit</code> and <code>rollback</code> functions for transaction control.</li>
<li><code>once</code> member, which is used for performing <em>instant</em> queries that do not need to be separately prepared. Example:</li>
</ul>
<pre><code class="language-cpp">sql.once << "drop table persons";
</code></pre>
<ul>
<li><code>prepare</code> member, which is used for statement preparation - the result of the statement preparation must be provided to the constructor of the <code>statement</code> class. Example:</li>
</ul>
<pre><code class="language-cpp">int i;
statement st = (sql.prepare <<
"insert into numbers(value) values(:val)", use(i));
</code></pre>
<ul>
<li><code>operator<<</code> that is a shortcut forwarder to the equivalent operator of the <code>once</code> member. Example:</li>
</ul>
<pre><code class="language-cpp">sql << "drop table persons";
</code></pre>
<ul>
<li><code>got_data</code> returns true if the last executed query had non-empty result.</li>
<li><code>get_next_sequence_value</code> returns true if the next value of the sequence with the specified name was generated and returned in its second argument. Unless you can be sure that your program will use only databases that support sequences, consider using this method in conjunction with <code>get_last_insert_id()</code> as explained in <a href="../../beyond/#sequences">"Working with sequences"</a> section.</li>
<li><code>get_last_insert_id</code> returns true if it could retrieve the last value automatically generated by the database for an auto-incremented field. Notice that although this method takes the table name, for some databases, such as Microsoft SQL Server and SQLite, this value is actually global, so you should attempt to retrieve it immediately after performing an insertion.</li>
<li><code>get_query_stream</code> provides direct access to the stream object that is used to accumulate the query text and exists in particular to allow the user to imbue specific locale to this stream.</li>
<li><code>set_log_stream</code> and <code>get_log_stream</code> functions for setting and getting the current stream object used for basic query logging. By default, it is <code>NULL</code>, which means no logging The string value that is actually logged into the stream is one-line verbatim copy of the query string provided by the user, without including any data from the <code>use</code> elements. The query is logged exactly once, before the preparation step.</li>
<li><code>get_last_query</code> retrieves the text of the last used query.</li>
<li><code>uppercase_column_names</code> allows to force all column names to uppercase in dynamic row description; this function is particularly useful for portability, since various database servers report column names differently (some preserve case, some change it).</li>
<li><code>get_dummy_from_table</code> and <code>get_dummy_from_clause()</code>: helpers for writing portable DML statements, see <a href="../../utilities/#dml">DML helpers</a> for more details.</li>
<li><code>get_backend</code> returns the internal pointer to the concrete backend implementation of the session. This is provided for advanced users that need access to the functionality that is not otherwise available.</li>
<li><code>get_backend_name</code> is a convenience forwarder to the same function of the backend object.</li>
</ul>
<p>See <a href="../../connections/">connection</a> and <a href="../../queries/">queries</a> for more examples.</p>
<h2 id="class-connection_parameters">class connection_parameters</h2>
<p>The <code>connection_parameters</code> class is a simple container for the backend pointer, connection string and any other connection options. It is used together with <code>session</code> constructor and <code>open()</code> method.</p>
<pre><code class="language-cpp">class connection_parameters
{
public:
connection_parameters();
connection_parameters(backend_factory const & factory, std::string const & connectString);
connection_parameters(std::string const & backendName, std::string const & connectString);
explicit connection_parameters(std::string const & fullConnectString);
void set_option(const char * name, std::string const & value);
bool get_option(const char * name, std::string & value) const;
bool is_option_on(const char * name) const;
};
</code></pre>
<p>The methods of this class are:</p>
<ul>
<li>Default constructor is rarely used as it creates an uninitialized object and the only way to initialize it later is to assign another, valid, connection_parameters object to this one.</li>
<li>The other constructors correspond to the similar constructors of the <code>session</code> class and specify both the backend, either as a pointer to it or by name, and the connection string.</li>
<li><code>set_option</code> can be used to set the value of an option with the given name. Currently all option values are strings, so if you need to set a numeric option you need to convert it to a string first. If an option with the given name had been already set before, its old value is overwritten.</li>
<li><code>get_option</code> can be used to query the value of an option and returns <code>false</code> if there is no such option, while <code>is_option_on</code> simply checks if the option is specified with the value <code>soci::option_true</code> (which is a symbolic constant standing for the string <code>"1"</code>).</li>
</ul>
<h2 id="class-connection_pool">class connection_pool</h2>
<p>The <code>connection_pool</code> class encapsulates the thread-safe pool of connections and ensures that only one thread at a time has access to any connection that it manages.</p>
<pre><code class="language-cpp">class connection_pool
{
public:
explicit connection_pool(std::size_t size);
~connection_pool();
session & at(std::size_t pos);
std::size_t lease();
bool try_lease(std::size_t & pos, int timeout);
void give_back(std::size_t pos);
};
</code></pre>
<p>The operations of the pool are:</p>
<ul>
<li>Constructor that takes the intended size of the pool. After construction, the pool contains regular <code>session</code> objects in disconnected state.</li>
<li><code>at</code> function that provides direct access to any given entryin the pool. This function is <em>non-synchronized</em>.</li>
<li><code>lease</code> function waits until some entry is available (which means that it is not used) and returns the position of that entry in the pool, marking it as <em>locked</em>.</li>
<li><code>try_lease</code> acts like <code>lease</code>, but allows to set up a time-out (relative, in milliseconds) on waiting. Negative time-out value means no time-out. Returns <code>true</code> if the entry was obtained, in which case its position is written to the <code>pos</code> parametr, and <code>false</code> if no entry was available before the time-out.</li>
<li><code>give_back</code> should be called when the entry on the given position is no longer in use and can be passed to other requesting thread.</li>
</ul>
<h2 id="class-transaction">class transaction</h2>
<p>The class <code>transaction</code> can be used for associating the transaction with some code scope. It is a RAII wrapper for regular transaction operations that automatically rolls back in its destructor <em>if</em> the transaction was not explicitly committed before.</p>
<pre><code class="language-cpp">class transaction
{
public:
explicit transaction(session & sql);
~transaction();
void commit();
void rollback();
private:
// ...
};
</code></pre>
<p>Note that objects of this class are not notified of other transaction related operations that might be executed by user code explicitly or hidden inside SQL queries. It is not recommended to mix different ways of managing transactions.</p>
<h2 id="function-into">function into</h2>
<p>The function <code>into</code> is used for binding local output data (in other words, it defines where the results of the query are stored).</p>
<pre><code class="language-cpp">template <typename T>
IT into(T & t);
template <typename T, typename T1>
IT into(T & t, T1 p1);
template <typename T>
IT into(T & t, indicator & ind);
template <typename T, typename T1>
IT into(T & t, indicator & ind, T1 p1);
template <typename T>
IT into(T & t, std::vector<indicator> & ind);
</code></pre>
<p>Example:</p>
<pre><code class="language-cpp">int count;
sql << "select count(*) from person", into(count);
</code></pre>
<p>See <a href="../../binding/#binding-output-data-into">Binding output data</a> for more examples</p>
<h2 id="function-use">function use</h2>
<p>The function <code>use</code> is used for binding local input data (in other words, it defines where the parameters of the query come from).</p>
<pre><code class="language-cpp">template <typename T>
*IT* use(T & t);
template <typename T, typename T1>
*IT* use(T & t, T1 p1);
template <typename T>
*IT* use(T & t, indicator & ind);
template <typename T, typename T1>
*IT* use(T & t, indicator & ind, T1 p1);
template <typename T>
*IT* use(T & t, std::vector<indicator> const & ind);
template <typename T, typename T1>
*IT* use(T & t, std::vector<indicator> const & ind, T1 p1);
</code></pre>
<p>Example:</p>
<pre><code class="language-cpp">int val = 7;
sql << "insert into numbers(val) values(:val)", use(val);
</code></pre>
<p>See <a href="../../binding/#binding-input-data-use">Binding input data</a> for more examples.</p>
<h2 id="class-statement">class statement</h2>
<p>The <code>statement</code> class encapsulates the prepared statement.</p>
<pre><code class="language-cpp">class statement
{
public:
statement(session & s);
statement(*IT* const & prep);
~statement();
statement(statement const & other);
void operator=(statement const & other);
void alloc();
void bind(values & v);
void exchange(*IT* const & i);
void exchange(*IT* const & u);
void clean_up();
void bind_clean_up();
void prepare(std::string const & query);
void define_and_bind();
bool execute(bool withDataExchange = false);
long long get_affected_rows();
bool fetch();
bool got_data() const;
void describe();
void set_row(row * r);
void exchange_for_rowset(*IT* const & i);
details::statement_backend * get_backend();
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li>Constructor accepting the <code>session</code> object. This can be used for later query preparation. Example:</li>
</ul>
<pre><code class="language-cpp">statement stmt(sql);
</code></pre>
<ul>
<li>Constructor accepting the result of using <code>prepare</code> on the <code>session</code> object, see example provided above for the <code>session</code> class.</li>
<li>Copy operations.</li>
<li><code>alloc</code> function, which allocates necessary internal resources.</li>
<li><code>bind</code> function, which is used to bind the <code>values</code> object - this is used in the object-relational mapping and normally called automatically.</li>
<li>exchange functions for registering the binding of local data - they expect the result of calling the <code>into</code> or <code>use</code> functions and are normally invoked automatically.</li>
<li><code>clean_up</code> function for cleaning up resources, normally called automatically.</li>
<li><code>bind_clean_up</code> function for cleaning up any bound references. It allows to keep statement in cache and reuse it later with new references by calling <code>exchange</code> for each new bind variable.</li>
<li><code>prepare</code> function for preparing the statement for repeated execution.</li>
<li><code>define_and_bind</code> function for actually executing the registered bindings, normally called automatically.</li>
<li><code>execute</code> function for executing the statement. If its parameter is <code>false</code> then there is no data exchange with locally bound variables (this form should be used if later <code>fetch</code> of multiple rows is foreseen). Returns <code>true</code> if there was at least one row of data returned.</li>
<li><code>get_affected_rows</code> function returns the number of rows affected by the last statement. Returns <code>-1</code> if it's not implemented by the backend being used.</li>
<li><code>fetch</code> function for retrieving the next portion of the result. Returns <code>true</code> if there was new data.</li>
<li><code>got_data</code> return <code>true</code> if the most recent execution returned any rows.</li>
<li><code>describe</code> function for extracting the type information for the result (<strong>Note:</strong> no data is exchanged). This is normally called automatically and only when dynamic resultset binding is used.</li>
<li><code>set_row</code> function for associating the <code>statement</code> and <code>row</code> objects, normally called automatically.</li>
<li><code>exchange_for_rowset</code> as a special case for binding <code>rowset</code> objects.</li>
<li><code>get_backend</code> function that returns the internal pointer to the concrete backend implementation of the statement object. This is provided for advanced users that need access to the functionality that is not otherwise available.</li>
</ul>
<p>See <a href="../../statements/">Statement preparation and repeated execution</a> for example uses.</p>
<p>Most of the functions from the <code>statement</code> class interface are called automatically, but can be also used explicitly. See <a href="../../interfaces/">Interfaces</a> for the description of various way to use this interface.</p>
<h2 id="class-procedure">class procedure</h2>
<p>The <code>procedure</code> class encapsulates the call to the stored procedure and is aimed for higher portability of the client code.</p>
<pre><code class="language-cpp">class procedure
{
public:
procedure(*IT* const & prep);
bool execute(bool withDataExchange = false);
bool fetch();
bool got_data() const;
};
</code></pre>
<p>The constructor expects the result of using <code>prepare</code> on the <code>session</code> object.</p>
<p>See <a href="../../procedures/">Stored procedures</a> for examples.</p>
<h2 id="class-type_conversion">class type_conversion</h2>
<p>The <code>type_conversion</code> class is a traits class that is supposed to be provided (specialized) by the user for defining conversions to and from one of the basic SOCI types.</p>
<pre><code class="language-cpp">template <typename T>
struct type_conversion
{
typedef T base_type;
static void from_base(base_type const & in, indicator ind, T & out);
static void to_base(T const & in, base_type & out, indicator & ind);
};
</code></pre>
<p>Users are supposed to properly implement the <code>from_base</code> and <code>to_base</code> functions in their specializations of this template class.</p>
<p>See <a href="../../types/#user-defined-c-types">Extending SOCI to support custom (user-defined) C++ types</a>.</p>
<h2 id="class-row">class row</h2>
<p>The <code>row</code> class encapsulates the data and type information retrieved for the single row when the dynamic rowset binding is used.</p>
<pre><code class="language-cpp">class row
{
public:
row();
~row();
void uppercase_column_names(bool forceToUpper);
std::size_t size() const;
indicator get_indicator(std::size_t pos) const;
indicator get_indicator(std::string const & name) const;
column_properties const & get_properties (std::size_t pos) const;
column_properties const & get_properties (std::string const & name) const;
template <typename T>
T get(std::size_t pos) const;
template <typename T>
T get(std::size_t pos, T const & nullValue) const;
template <typename T>
T get(std::string const & name) const;
template <typename T>
T get(std::string const & name, T const & nullValue) const;
template <typename T>
row const & operator>>(T & value) const;
void skip(std::size_t num = 1) const;
void reset_get_counter() const
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li>Default constructor that allows to declare a <code>row</code> variable.</li>
<li><code>uppercase_column_names</code> - see the same function in the <code>session</code> class.</li>
<li><code>size</code> function that returns the number of columns in the row.</li>
<li><code>get_indicator</code> function that returns the indicator value for the given column (column is specified by position - starting from 0 - or by name).</li>
<li><code>get_properties</code> function that returns the properties of the column given by position (starting from 0) or by name.</li>
<li><code>get</code> functions that return the value of the column given by position or name. If the column contains null, then these functions either return the provided "default" <code>nullValue</code> or throw an exception.</li>
<li><code>operator>></code> for convenience stream-like extraction interface. Subsequent calls to this function are equivalent to calling <code>get</code> with increasing position parameter, starting from the beginning.</li>
<li><code>skip</code> and <code>reset_get_counter</code> allow to change the order of data extraction for the above operator.</li>
</ul>
<p>See <a href="../../types/#dynamic-binding">Dynamic resultset binding</a> for examples.</p>
<h2 id="class-column_properties">class column_properties</h2>
<p>The <code>column_properties</code> class provides the type and name information about the particular column in a rowset.</p>
<pre><code class="language-cpp">class column_properties
{
public:
std::string get_name() const;
db_type get_db_type() const;
data_type_type get_data_type() const;
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li><code>get_name</code> function that returns the name of the column.</li>
<li><code>get_db_type</code> that returns the type of the column.</li>
<li><code>get_data_type</code> that returns the type of the column (deprecated in favor of <code>get_db_type</code>).</li>
</ul>
<p>See <a href="../../types/#dynamic-binding">Dynamic resultset binding</a> for examples.</p>
<h2 id="class-values">class values</h2>
<p>The <code>values</code> class encapsulates the data and type information and is used for object-relational mapping.</p>
<pre><code class="language-cpp">class values
{
public:
values();
void uppercase_column_names(bool forceToUpper);
indicator get_indicator(std::size_t pos) const;
indicator get_indicator(std::string const & name) const;
template <typename T>
T get(std::size_t pos) const;
template <typename T>
T get(std::size_t pos, T const & nullValue) const;
template <typename T>
T get(std::string const & name) const;
template <typename T>
T get(std::string const & name, T const & nullValue) const;
template <typename T>
values const & operator>>(T & value) const;
void skip(std::size_t num = 1) const;
void reset_get_counter() const;
template <typename T>
void set(std::string const & name, T const & value, indicator indic = i_ok);
template <typename T>
void set(const T & value, indicator indic = i_ok);
template <typename T>
values & operator<<(T const & value);
};
</code></pre>
<p>This class contains the same members as the <code>row</code> class (with the same meaning) plus:</p>
<ul>
<li><code>set</code> function for storing values in named columns or in subsequent positions.</li>
<li><code>operator<<</code> for convenience.</li>
</ul>
<p>See <a href="../../types/#object-relational-mapping">Object-relational mapping</a> for examples.</p>
<h2 id="class-blob">class blob</h2>
<p>The <code>blob</code> class encapsulates the "large object" functionality.</p>
<pre><code class="language-cpp">class blob
{
public:
explicit blob(session & s);
~blob();
std::size_t getLen();
std::size_t read(std::size_t offset, char * buf, std::size_t toRead);
std::size_t write(std::size_t offset, char const * buf, std::size_t toWrite);
std::size_t append(char const * buf, std::size_t toWrite);
void trim(std::size_t newLen);
details::blob_backend * get_backend();
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li>Constructor associating the <code>blob</code> object with the <code>session</code> object.</li>
<li><code>get_len</code> function that returns the size of the BLOB object.</li>
<li><code>read</code> function that reads the BLOB data into provided buffer.</li>
<li><code>write</code> function that writes the BLOB data from provided buffer.</li>
<li><code>append</code> function that appends to the existing BLOB data.</li>
<li><code>trim</code> function that truncates the existing data to the new length.</li>
<li><code>get_backend</code> function that returns the internal pointer to the concrete backend implementation of the BLOB object. This is provided for advanced users that need access to the functionality that is not otherwise available.</li>
</ul>
<p>See <a href="../../lobs/">Large objects (BLOBs)</a> for more discussion.</p>
<h2 id="class-rowid">class rowid</h2>
<p>The <code>rowid</code> class encapsulates the "row identifier" object.</p>
<pre><code class="language-cpp">class rowid
{
public:
explicit rowid(Session & s);
~rowid();
details::rowid_backend * get_backend();
};
</code></pre>
<p>This class contains the following members:</p>
<ul>
<li>Constructor associating the <code>rowid</code> object with the <code>session</code> object.</li>
<li><code>get_backend</code> function that returns the internal pointer to the concrete backend implementation of the <code>rowid</code> object.</li>
</ul>
<h2 id="class-backend_factory">class backend_factory</h2>
<p>The <code>backend_factory</code> class provides the abstract interface for concrete backend factories.</p>
<pre><code class="language-cpp">struct backend_factory
{
virtual details::session_backend * make_session(
std::string const & connectString) const = 0;
};
</code></pre>
<p>The only member of this class is the <code>make_session</code> function that is supposed to create concrete backend implementation of the session object.</p>
<p>Objects of this type are declared by each backend and should be provided to the constructor of the <code>session</code> class. In simple programs users do not need to use this class directly, but the example use is:</p>
<pre><code class="language-cpp">backend_factory & factory = postgresql;
std::string connectionParameters = "dbname=mydb";
session sql(factory, parameters);
</code></pre>
<h2 id="simple-client-interface">Simple Client Interface</h2>
<p>The simple client interface is provided with other languages in mind, to allow easy integration of the SOCI library with script interpreters and those languages that have the ability to link directly with object files using the "C" calling convention.</p>
<p>The functionality of this interface is limited and in particular the dynamic rowset description and type conversions are not supported in this release. On the other hand, the important feature of this interface is that it does not require passing pointers to data managed by the user, because all data is handled at the SOCI side. This should make it easier to integrate SOCI with languages that have constrained ability to understand the C type system.</p>
<p>Users of this interface need to explicitly <code>#include <soci-simple.h></code>.</p>
<pre><code class="language-c">typedef void * session_handle;
session_handle soci_create_session(char const * connectionString);
void soci_destroy_session(session_handle s);
void soci_begin(session_handle s);
void soci_commit(session_handle s);
void soci_rollback(session_handle s);
int soci_session_state(session_handle s);
char const * soci_session_error_message(session_handle s);
</code></pre>
<p>The functions above provide the <em>session</em> abstraction with the help of opaque handle. The <code>soci_session_state</code> function returns <code>1</code> if there was no error during the most recently executed function and <code>0</code> otherwise, in which case the <code>soci_session_error_message</code> can be used to obtain a human-readable error description.</p>
<p>Note that the only function that cannot report all errors this way is <code>soci_create_session</code>, which returns <code>NULL</code> if it was not possible to create an internal object representing the session. However, if the proxy object was created, but the connection could not be established for whatever reason, the error message can be obtained in the regular way.</p>
<pre><code class="language-c">typedef void *blob_handle;
blob_handle soci_create_blob(session_handle s);
void soci_destroy_blob(blob_handle b);
int soci_blob_get_len(blob_handle b);
int soci_blob_read(blob_handle b, int offset, char *buf, int toRead);
int soci_blob_write(blob_handle b, int offset, char const *buf, int toWrite);
int soci_blob_append(blob_handle b, char const *buf, int toWrite);
int soci_blob_trim(blob_handle b, int newLen);
int soci_blob_state(blob_handle b);
char const * soci_blob_error_message(blob_handle b);
</code></pre>
<p>The functions above provide the <em>blob</em> abstraction with the help of opaque handle. The <code>soci_blob_state</code> function returns <code>1</code> if there was no error during the most recently executed function and <code>0</code> otherwise, in which case the <code>soci_session_error_message</code> can be used to obtain a human-readable error description.</p>
<p>For easy error testing, functions <code>soci_blob_read</code>, <code>soci_blob_write</code>, <code>soci_blob_append</code>, and <code>soci_blob_trim</code> return <code>-1</code> in case of error and <code>soci_session_error_message</code> can be used to obtain a human-readable error description.</p>
<p>Note that the only function that cannot report all errors this way is <code>soci_create_blob</code>, which returns <code>NULL</code> if it was not possible to create an internal object representing the blob.</p>
<pre><code class="language-c">typedef void * statement_handle;
statement_handle soci_create_statement(session_handle s);
void soci_destroy_statement(statement_handle st);
int soci_statement_state(statement_handle s);
char const * soci_statement_error_message(statement_handle s);
</code></pre>
<p>The functions above create and destroy the statement object. If the statement cannot be created by the <code>soci_create_statement</code> function, the error condition is set up in the related session object; for all other functions the error condition is set in the statement object itself.</p>
<pre><code class="language-c">int soci_into_string (statement_handle st);
int soci_into_int (statement_handle st);
int soci_into_long_long(statement_handle st);
int soci_into_int8 (statement_handle st);
int soci_into_uint8 (statement_handle st);
int soci_into_int16 (statement_handle st);
int soci_into_uint16 (statement_handle st);
int soci_into_int32 (statement_handle st);
int soci_into_uint32 (statement_handle st);
int soci_into_int64 (statement_handle st);
int soci_into_uint64 (statement_handle st);
int soci_into_double (statement_handle st);
int soci_into_date (statement_handle st);
int soci_into_blob (statement_handle st);
int soci_into_string_v (statement_handle st);
int soci_into_int_v (statement_handle st);
int soci_into_long_long_v(statement_handle st);
int soci_into_int8_v (statement_handle st);
int soci_into_uint8_v (statement_handle st);
int soci_into_int16_v (statement_handle st);
int soci_into_uint16_v (statement_handle st);
int soci_into_int32_v (statement_handle st);
int soci_into_uint32_v (statement_handle st);
int soci_into_int64_v (statement_handle st);
int soci_into_uint64_v (statement_handle st);
int soci_into_double_v (statement_handle st);
int soci_into_date_v (statement_handle st);
</code></pre>
<p>These functions create new data items for storing query results (<em>into elements</em>). These elements can be later identified by their position, which is counted from 0. For convenience, these function return the position of the currently added element. In case of error, <code>-1</code> is returned and the error condition is set in the statement object.</p>
<p>The <code>_v</code> versions create a <code>vector</code> into elements, which can be used
to retrieve whole arrays of results.</p>
<pre><code class="language-c">int soci_get_into_state(statement_handle st, int position);
int soci_get_into_state_v(statement_handle st, int position, int index);
</code></pre>
<p>This function returns <code>1</code> if the into element at the given position has non-null value and <code>0</code> otherwise. The <code>_v</code> version works with <code>vector</code> elements and expects an array index.</p>
<pre><code class="language-c">char const * soci_get_into_string (statement_handle st, int position);
int soci_get_into_int (statement_handle st, int position);
long long soci_get_into_long_long(statement_handle st, int position);
int8_t soci_get_into_int8 (statement_handle st, int position);
uint8_t soci_get_into_uint8 (statement_handle st, int position);
int16_t soci_get_into_int16 (statement_handle st, int position);
uint16_t soci_get_into_uint16 (statement_handle st, int position);
int32_t soci_get_into_int32 (statement_handle st, int position);
uint32_t soci_get_into_uint32 (statement_handle st, int position);
int64_t soci_get_into_int64 (statement_handle st, int position);
uint64_t soci_get_into_uint64 (statement_handle st, int position);
double soci_get_into_double (statement_handle st, int position);
char const * soci_get_into_date (statement_handle st, int position);
blob_handle soci_get_into_blob (statement_handle st, int position);
char const * soci_get_into_string_v (statement_handle st, int position, int index);
int soci_get_into_int_v (statement_handle st, int position, int index);
long long soci_get_into_long_long_v(statement_handle st, int position, int index);
int8_t soci_get_into_int8_v (statement_handle st, int position, int index);
uint8_t soci_get_into_uint8_v (statement_handle st, int position, int index);
int16_t soci_get_into_int16_v (statement_handle st, int position, int index);
uint16_t soci_get_into_uint16_v (statement_handle st, int position, int index);
int32_t soci_get_into_int32_v (statement_handle st, int position, int index);
uint32_t soci_get_into_uint32_v (statement_handle st, int position, int index);
int64_t soci_get_into_int64_v (statement_handle st, int position, int index);
uint64_t soci_get_into_uint64_v (statement_handle st, int position, int index);
double soci_get_into_double_v (statement_handle st, int position, int index);
char const * soci_get_into_date_v (statement_handle st, int position, int index);
</code></pre>
<p>The functions above allow to retrieve the current value of the given into element.</p>
<p><strong>Note:</strong> The <code>date</code> function returns the date value in the "<code>YYYY MM DD HH mm ss</code>" string format.</p>
<pre><code class="language-c">void soci_use_string (statement_handle st, char const * name);
void soci_use_int (statement_handle st, char const * name);
void soci_use_long_long(statement_handle st, char const * name);
void soci_use_int8 (statement_handle st, char const * name);
void soci_use_uint8 (statement_handle st, char const * name);
void soci_use_int16 (statement_handle st, char const * name);
void soci_use_uint16 (statement_handle st, char const * name);
void soci_use_int32 (statement_handle st, char const * name);
void soci_use_uint32 (statement_handle st, char const * name);
void soci_use_int64 (statement_handle st, char const * name);
void soci_use_uint64 (statement_handle st, char const * name);
void soci_use_double (statement_handle st, char const * name);
void soci_use_date (statement_handle st, char const * name);
void soci_use_blob (statement_handle st, char const * name);
void soci_use_string_v (statement_handle st, char const * name);
void soci_use_int_v (statement_handle st, char const * name);
void soci_use_long_long_v(statement_handle st, char const * name);
void soci_use_int8_v (statement_handle st, char const * name);
void soci_use_uint8_v (statement_handle st, char const * name);
void soci_use_int16_v (statement_handle st, char const * name);
void soci_use_uint16_v (statement_handle st, char const * name);
void soci_use_int32_v (statement_handle st, char const * name);
void soci_use_uint32_v (statement_handle st, char const * name);
void soci_use_int64_v (statement_handle st, char const * name);
void soci_use_uint64_v (statement_handle st, char const * name);
void soci_use_double_v (statement_handle st, char const * name);
void soci_use_date_v (statement_handle st, char const * name);
</code></pre>
<p>The functions above allow to create new data elements that will be used to provide data to the query (<em>use elements</em>). The new elements can be later identified by given name, which must be unique for the given statement.</p>
<pre><code class="language-c">void soci_set_use_state(statement_handle st, char const * name, int state);
</code></pre>
<p>The <code>soci_set_use_state</code> function allows to set the state of the given use element. If the <code>state</code> parameter is set to non-zero the use element is considered non-null (which is also the default state after creating the use element).</p>
<pre><code class="language-c">int soci_use_get_size_v(statement_handle st);
void soci_use_resize_v (statement_handle st, int new_size);
</code></pre>
<p>These functions get and set the size of vector use elements (see comments for vector into elements above).</p>
<pre><code class="language-c">void soci_set_use_string (statement_handle st, char const * name, char const * val);
void soci_set_use_int (statement_handle st, char const * name, int val);
void soci_set_use_long_long(statement_handle st, char const * name, long long val);
void soci_set_use_int8 (statement_handle st, char const * name, int8_t val);
void soci_set_use_uint8 (statement_handle st, char const * name, uint8_t val);
void soci_set_use_int16 (statement_handle st, char const * name, int16_t val);
void soci_set_use_uint16 (statement_handle st, char const * name, uint16_t val);
void soci_set_use_int32 (statement_handle st, char const * name, int32_t val);
void soci_set_use_uint32 (statement_handle st, char const * name, uint32_t val);
void soci_set_use_int64 (statement_handle st, char const * name, int64_t val);
void soci_set_use_uint64 (statement_handle st, char const * name, uint64_t val);
void soci_set_use_double (statement_handle st, char const * name, double val);
void soci_set_use_date (statement_handle st, char const * name, char const * val);
void soci_set_use_blob (statement_handle st, char const * name, blob_handle blob);
void soci_set_use_state_v (statement_handle st, char const * name, int index, int state);
void soci_set_use_string_v (statement_handle st, char const * name, int index, char const * val);
void soci_set_use_int_v (statement_handle st, char const * name, int index, int val);
void soci_set_use_long_long_v(statement_handle st, char const * name, int index, long long val);
void soci_set_use_int8_v (statement_handle st, char const * name, int index, int8_t val);
void soci_set_use_uint8_v (statement_handle st, char const * name, int index, uint8_t val);
void soci_set_use_int16_v (statement_handle st, char const * name, int index, int16_t val);
void soci_set_use_uint16_v (statement_handle st, char const * name, int index, uint16_t val);
void soci_set_use_int32_v (statement_handle st, char const * name, int index, int32_t val);
void soci_set_use_uint32_v (statement_handle st, char const * name, int index, uint32_t val);
void soci_set_use_int64_v (statement_handle st, char const * name, int index, int64_t val);
void soci_set_use_uint64_v (statement_handle st, char const * name, int index, uint64_t val);
void soci_set_use_double_v (statement_handle st, char const * name, int index, double val);
void soci_set_use_date_v (statement_handle st, char const * name, int index, char const * val);
</code></pre>
<p>The functions above set the value of the given use element, for both single and vector elements.</p>
<p><strong>Note:</strong> The expected format for the data values is "<code>YYYY MM DD HH mm ss</code>".</p>
<pre><code class="language-c">int soci_get_use_state (statement_handle st, char const * name);
char const * soci_get_use_string (statement_handle st, char const * name);
int soci_get_use_int (statement_handle st, char const * name);
long long soci_get_use_long_long(statement_handle st, char const * name);
int8_t soci_get_use_int8 (statement_handle st, char const * name);
uint8_t soci_get_use_uint8 (statement_handle st, char const * name);
int16_t soci_get_use_int16 (statement_handle st, char const * name);
uint16_t soci_get_use_uint16 (statement_handle st, char const * name);
int32_t soci_get_use_int32 (statement_handle st, char const * name);
uint32_t soci_get_use_uint32 (statement_handle st, char const * name);
int64_t soci_get_use_int64 (statement_handle st, char const * name);
uint64_t soci_get_use_uint64 (statement_handle st, char const * name);
double soci_get_use_double (statement_handle st, char const * name);
char const * soci_get_use_date (statement_handle st, char const * name);
blob_handle soci_get_use_blob (statement_handle st, char const * name);
</code></pre>
<p>These functions allow to inspect the state and value of named use elements.</p>
<p><strong><em>Note:</em></strong> these functions are provide only for single use elements, not for vectors; the rationale for this is that modifiable use elements are not supported for bulk operations.</p>
<pre><code class="language-c">void soci_prepare(statement_handle st, char const * query);
int soci_execute(statement_handle st, int withDataExchange);
int soci_fetch(statement_handle st);
int soci_got_data(statement_handle st);
</code></pre>
<p>The functions above provide the core execution functionality for the statement object and their meaning is equivalent to the respective functions in the core C++ interface described above.</p></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Copyright © 2017-2025 <a href="https://soci.sourceforge.net/people.html">SOCI Team</a>.</p>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../../js/bootstrap.bundle.min.js"></script>
<script>
var base_url = "../..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../../js/base.js"></script>
<script src="../../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
|
