Contents

I

Table of Contents
Part I What's New

1

Part II General Information

11

1 Overview................................................................................................................................... 12
2 Features................................................................................................................................... 15
3 Requirements................................................................................................................................... 18
4 Compatibility................................................................................................................................... 18
5 Using...................................................................................................................................
Several DAC Products in One IDE
23
6 Component...................................................................................................................................
List
23
7 Hierarchy...................................................................................................................................
Chart
25
8 Editions................................................................................................................................... 27
9 Licensing................................................................................................................................... 29
10 Getting...................................................................................................................................
Support33
11 Frequently...................................................................................................................................
Asked Questions
34

Part III Getting Started

41

1 Installation................................................................................................................................... 41
2 Migration...................................................................................................................................
Wizard44
3 Migration...................................................................................................................................
from BDE
45
4 Migration...................................................................................................................................
from ADO48
5 Logging...................................................................................................................................
on to SQL Server
51
6 Logging...................................................................................................................................
on to SQL Server Compact
57
7 Creating...................................................................................................................................
Database Objects
64
8 Deleting...................................................................................................................................
Data From Tables
69
9 Inserting...................................................................................................................................
Data Into Tables
72
10 Retrieving...................................................................................................................................
Data
77
11 Modifying...................................................................................................................................
Data
79
12 Stored...................................................................................................................................
Procedures
83
13 Working...................................................................................................................................
With Result Sets Using Stored Procedures
90
14 Demo...................................................................................................................................
Projects
92
15 Deployment................................................................................................................................... 100

Part IV Using SDAC

101

1 Connecting...................................................................................................................................
in Direct Mode102
2 Updating...................................................................................................................................
Data with SDAC Dataset Components
103
3 Master/Detail...................................................................................................................................
Relationships
104
4 Using...................................................................................................................................
Table-Valued Parameters106© 2019 Devart

II

SQL Server Data Access Components
5 Data...................................................................................................................................
Type Mapping
107
6 Data...................................................................................................................................
Encryption
113
7 Working...................................................................................................................................
in an Unstable Network
115
8 Disconnected...................................................................................................................................
Mode
116
9 Performance...................................................................................................................................
of Obtaining Data
117
10 Batch...................................................................................................................................
Operations
118
11 Increasing...................................................................................................................................
Performance
122
12 Macros................................................................................................................................... 124
13 DataSet...................................................................................................................................
Manager125
14 SQL ...................................................................................................................................
Server Compact Edition
130
15 Working...................................................................................................................................
with User Defined Types (UDT)131
16 TMSTransaction...................................................................................................................................
Component
133
17 DBMonitor................................................................................................................................... 134
18 Writing...................................................................................................................................
GUI Applications with SDAC
135
19 Connection...................................................................................................................................
Pooling
135
20 Compatibility...................................................................................................................................
with Previous Versions
137
21 64-bit...................................................................................................................................
Development with Embarcadero RAD Studio XE2
139
22 Integration...................................................................................................................................
with dbForge Studio for SQL Server
144
23 Database...................................................................................................................................
Specific Aspects of 64-bit Development
148
24 FILESTREAM...................................................................................................................................
Data
148

Part V Reference

151

1 CRAccess................................................................................................................................... 153.......................................................................................................................................................... 154
Classes.........................................................................................................................................................
154
TCRCursor
Class......................................................................................................................................... 155
Members.......................................................................................................................................................... 155
Types.........................................................................................................................................................
156
TBeforeFetchProc
Procedure Reference.......................................................................................................................................................... 156
Enum erations.........................................................................................................................................................
156
TCRIsolationLevel
Enumeration.........................................................................................................................................................
157
TCRTransactionAction
Enumeration.........................................................................................................................................................
157
TCursorState
Enumeration

2 CRBatchMove................................................................................................................................... 158.......................................................................................................................................................... 159
Classes.........................................................................................................................................................
159
TCRBatchMove
Class......................................................................................................................................... 160
Members......................................................................................................................................... 162
Properties...................................................................................................................................
164
AbortOnKeyViol
Property...................................................................................................................................
164
AbortOnProblem
Property
164
ChangedCount...................................................................................................................................
Property................................................................................................................................... 165
CommitCount Property................................................................................................................................... 165
Destination Property...................................................................................................................................
166
FieldMappingMode
Property................................................................................................................................... 166
KeyViolCount Property................................................................................................................................... 167
Mappings Property
Mode Property................................................................................................................................... 167© 2019 Devart

Contents

III................................................................................................................................... 168
MovedCount Property................................................................................................................................... 168
ProblemCount Property................................................................................................................................... 169
RecordCount Property................................................................................................................................... 169
Source Property......................................................................................................................................... 170
Methods................................................................................................................................... 170
Execute Method......................................................................................................................................... 171
Events...................................................................................................................................
171
OnBatchMoveProgress
Event.......................................................................................................................................................... 172
Types.........................................................................................................................................................
172
TCRBatchMoveProgressEvent
Procedure Reference.......................................................................................................................................................... 172
Enum erations.........................................................................................................................................................
173
TCRBatchMode
Enumeration.........................................................................................................................................................
173
TCRFieldMappingMode
Enumeration

3 CREncryption................................................................................................................................... 174.......................................................................................................................................................... 175
Classes.........................................................................................................................................................
175
TCREncryptor
Class.........................................................................................................................................
175
Members.........................................................................................................................................
176
Properties...................................................................................................................................
177
DataHeader Property...................................................................................................................................
177
EncryptionAlgorithm Property...................................................................................................................................
178
HashAlgorithm Property...................................................................................................................................
178
InvalidHashAction Property...................................................................................................................................
179
Passw ord Property.........................................................................................................................................
179
Methods...................................................................................................................................
180
SetKey Method..........................................................................................................................................................
180
Enum erations.........................................................................................................................................................
181
TCREncDataHeader Enumeration.........................................................................................................................................................
181
TCREncryptionAlgorithm Enumeration.........................................................................................................................................................
182
TCRHashAlgorithm Enumeration.........................................................................................................................................................
183
TCRInvalidHashAction Enumeration

4 CRVio................................................................................................................................... 183.......................................................................................................................................................... 183
Enum erations.........................................................................................................................................................
183
TIPVersion
Enumeration

5 DAAlerter................................................................................................................................... 184.......................................................................................................................................................... 184
Classes.........................................................................................................................................................
185
TDAAlerterClass......................................................................................................................................... 185
Members......................................................................................................................................... 186
Properties
Active Property................................................................................................................................... 187................................................................................................................................... 187
AutoRegister Property......................................................................................................................................... 188
Methods................................................................................................................................... 188
SendEvent Method
Start Method ................................................................................................................................... 189
Stop Method ................................................................................................................................... 189......................................................................................................................................... 190
EventsOnError Event ................................................................................................................................... 190

6 DADump................................................................................................................................... 190.......................................................................................................................................................... 191
Classes
191
TDADump.........................................................................................................................................................
Class......................................................................................................................................... 192
Members......................................................................................................................................... 194
Properties................................................................................................................................... 194
Connection Property
Debug Property................................................................................................................................... 195© 2019 Devart

IV

SQL Server Data Access Components................................................................................................................................... 196
Options Property
SQL Property ................................................................................................................................... 196................................................................................................................................... 197
TableNames Property......................................................................................................................................... 197
Methods
Backup Method................................................................................................................................... 198................................................................................................................................... 199
BackupQuery Method................................................................................................................................... 199
BackupToFile Method...................................................................................................................................
200
BackupToStream
Method................................................................................................................................... 201
Restore Method...................................................................................................................................
201
RestoreFromFile
Method...................................................................................................................................
202
RestoreFromStream
Method......................................................................................................................................... 203
Events...................................................................................................................................
203
OnBackupProgress
Event
OnError Event ................................................................................................................................... 204...................................................................................................................................
205
OnRestoreProgress
Event.........................................................................................................................................................
205
TDADumpOptions
Class......................................................................................................................................... 206
Members......................................................................................................................................... 206
Properties................................................................................................................................... 207
AddDrop Property
207
CompleteInsert...................................................................................................................................
Property...................................................................................................................................
208
GenerateHeader
Property................................................................................................................................... 208
QuoteNames Property.......................................................................................................................................................... 209
Types.........................................................................................................................................................
209
TDABackupProgressEvent
Procedure Reference.........................................................................................................................................................
210
TDARestoreProgressEvent
Procedure Reference

7 DALoader................................................................................................................................... 210.......................................................................................................................................................... 211
Classes.........................................................................................................................................................
211
TDAColumnClass.........................................................................................................................................
212
Members.........................................................................................................................................
212
Properties...................................................................................................................................
213
FieldType Property...................................................................................................................................
213
Name Property.........................................................................................................................................................
214
TDAColumns Class.........................................................................................................................................
214
Members.........................................................................................................................................
214
Properties...................................................................................................................................
215
Items Property(Indexer).........................................................................................................................................................
215
TDALoader Class.........................................................................................................................................
216
Members.........................................................................................................................................
217
Properties...................................................................................................................................
218
Columns Property...................................................................................................................................
218
Connection Property...................................................................................................................................
219
TableName Property.........................................................................................................................................
219
Methods...................................................................................................................................
220
CreateColumns Method...................................................................................................................................
220
Load Method...................................................................................................................................
221
LoadFromDataSet Method...................................................................................................................................
222
PutColumnData Method...................................................................................................................................
222
PutColumnData Method...................................................................................................................................
223
PutColumnData Method.........................................................................................................................................
223
Events...................................................................................................................................
224
OnGetColumnData Event...................................................................................................................................
225
OnProgress Event...................................................................................................................................
225
OnPutData Event.........................................................................................................................................................
226
TDALoaderOptions Class© 2019 Devart

Contents

V......................................................................................................................................... 227
Members......................................................................................................................................... 227
Properties...................................................................................................................................
228
UseBlankValues
Property.......................................................................................................................................................... 228
Types.........................................................................................................................................................
228
TDAPutDataEvent
Procedure Reference.........................................................................................................................................................
229
TGetColumnDataEvent
Procedure Reference.........................................................................................................................................................
229
TLoaderProgressEvent
Procedure Reference

8 DAScript................................................................................................................................... 230.......................................................................................................................................................... 231
Classes.........................................................................................................................................................
231
TDAScript
Class.........................................................................................................................................
232
Members.........................................................................................................................................
234
Properties...................................................................................................................................
235
Connection Property...................................................................................................................................
236
DataSet Property...................................................................................................................................
236
Debug Property...................................................................................................................................
237
Delimiter Property...................................................................................................................................
237
EndLine Property...................................................................................................................................
238
EndOffset Property...................................................................................................................................
238
EndPos Property...................................................................................................................................
238
Macros Property...................................................................................................................................
239
SQL Property...................................................................................................................................
239
StartLine Property...................................................................................................................................
240
StartOffset Property...................................................................................................................................
240
StartPos Property...................................................................................................................................
241
Statements Property.........................................................................................................................................
242
Methods...................................................................................................................................
242
BreakExec Method...................................................................................................................................
243
ErrorOffset Method...................................................................................................................................
243
Execute Method...................................................................................................................................
244
ExecuteFile Method...................................................................................................................................
244
ExecuteNext Method...................................................................................................................................
245
ExecuteStream Method...................................................................................................................................
246
MacroByName Method.........................................................................................................................................
246
Events...................................................................................................................................
247
AfterExecute Event...................................................................................................................................
247
BeforeExecute Event...................................................................................................................................
248
OnError Event.........................................................................................................................................................
248
TDAStatement Class.........................................................................................................................................
249
Members.........................................................................................................................................
250
Properties...................................................................................................................................
251
EndLine Property...................................................................................................................................
251
EndOffset Property...................................................................................................................................
252
EndPos Property...................................................................................................................................
252
Omit Property...................................................................................................................................
252
Params Property...................................................................................................................................
253
Script Property...................................................................................................................................
253
SQL Property...................................................................................................................................
254
StartLine Property...................................................................................................................................
254
StartOffset Property...................................................................................................................................
255
StartPos Property.........................................................................................................................................
255
Methods...................................................................................................................................
255
Execute Method.........................................................................................................................................................
256
TDAStatements Class.........................................................................................................................................
256
Members© 2019 Devart

VI

SQL Server Data Access Components......................................................................................................................................... 257
Properties................................................................................................................................... 257
Items Property(Indexer).......................................................................................................................................................... 258
Types.........................................................................................................................................................
258
TAfterStatementExecuteEvent
Procedure Reference.........................................................................................................................................................
259
TBeforeStatementExecuteEvent
Procedure Reference.........................................................................................................................................................
259
TOnErrorEvent
Procedure Reference.......................................................................................................................................................... 260
Enum erations.........................................................................................................................................................
260
TErrorAction
Enumeration

9 DASQLMonitor................................................................................................................................... 261.......................................................................................................................................................... 262
Classes.........................................................................................................................................................
262
TCustomDASQLMonitor
Class.........................................................................................................................................
263
Members.........................................................................................................................................
263
Properties...................................................................................................................................
264
Active Property...................................................................................................................................
264
DBMonitorOptions Property...................................................................................................................................
265
Options Property...................................................................................................................................
265
TraceFlags Property.........................................................................................................................................
266
Events...................................................................................................................................
266
OnSQL Event.........................................................................................................................................................
267
TDBMonitorOptions Class.........................................................................................................................................
267
Members.........................................................................................................................................
268
Properties...................................................................................................................................
268
Host Property...................................................................................................................................
269
Port Property...................................................................................................................................
269
ReconnectTimeout Property...................................................................................................................................
270
SendTimeout Property..........................................................................................................................................................
270
Types
.........................................................................................................................................................
271
TDATraceFlags Set.........................................................................................................................................................
271
TMonitorOptions Set.........................................................................................................................................................
271
TOnSQLEvent Procedure Reference..........................................................................................................................................................
272
Enum erations.........................................................................................................................................................
272
TDATraceFlag Enumeration.........................................................................................................................................................
273
TMonitorOption Enumeration

10 DBAccess................................................................................................................................... 274.......................................................................................................................................................... 277
Classes279
EDAError.........................................................................................................................................................
Class......................................................................................................................................... 280
Members......................................................................................................................................... 280
Properties................................................................................................................................... 280
Component Property................................................................................................................................... 281
ErrorCode Property.........................................................................................................................................................
281
TCRDataSourceClass......................................................................................................................................... 282
Members.........................................................................................................................................................
282
TCustomConnectDialog
Class......................................................................................................................................... 282
Members......................................................................................................................................... 284
Properties................................................................................................................................... 285
CancelButton Property................................................................................................................................... 285
Caption Property
285
ConnectButton...................................................................................................................................
Property................................................................................................................................... 286
DialogClass Property................................................................................................................................... 286
LabelSet Property...................................................................................................................................
287
Passw ordLabel
Property................................................................................................................................... 287
Retries Property...................................................................................................................................
288
SavePassw ord
Property© 2019 Devart

ContentsVII................................................................................................................................... 288
ServerLabel Property................................................................................................................................... 288
StoreLogInfo Property...................................................................................................................................
289
UsernameLabel
Property......................................................................................................................................... 289
Methods................................................................................................................................... 290
Execute Method
290
GetServerList ...................................................................................................................................
Method.........................................................................................................................................................
291
TCustomDAConnection
Class......................................................................................................................................... 292
Members......................................................................................................................................... 294
Properties
295
ConnectDialog...................................................................................................................................
Property
295
ConnectString ...................................................................................................................................
Property................................................................................................................................... 298
ConvertEOL Property................................................................................................................................... 298
InTransaction Property................................................................................................................................... 299
LoginPrompt Property................................................................................................................................... 299
Options Property................................................................................................................................... 300
Passw ord Property................................................................................................................................... 301
Pooling Property
302
PoolingOptions...................................................................................................................................
Property................................................................................................................................... 302
Server Property................................................................................................................................... 303
Username Property......................................................................................................................................... 304
Methods
305
ApplyUpdates ...................................................................................................................................
Method305
ApplyUpdates ...................................................................................................................................
Method306
ApplyUpdates ...................................................................................................................................
MethodCommit Method................................................................................................................................... 307................................................................................................................................... 307
Connect Method................................................................................................................................... 308
CreateSQL Method................................................................................................................................... 308
Disconnect Method................................................................................................................................... 309
ExecProc Method................................................................................................................................... 311
ExecProcEx Method................................................................................................................................... 312
ExecSQL Method................................................................................................................................... 313
ExecSQLEx Method...................................................................................................................................
314
GetDatabaseNames
Method...................................................................................................................................
315
GetKeyFieldNames
Method...................................................................................................................................
315
GetStoredProcNames
Method...................................................................................................................................
316
GetTableNames
Method...................................................................................................................................
317
MonitorMessage
MethodPing Method ................................................................................................................................... 318...................................................................................................................................
318
RemoveFromPool
Method................................................................................................................................... 319
Rollback Method...................................................................................................................................
319
StartTransaction
Method......................................................................................................................................... 320
Events...................................................................................................................................
321
OnConnectionLost
Event
OnError Event ................................................................................................................................... 321.........................................................................................................................................................
322
TCustomDADataSet
Class......................................................................................................................................... 322
Members......................................................................................................................................... 330
Properties................................................................................................................................... 334
BaseSQL Property................................................................................................................................... 334
Conditions Property................................................................................................................................... 335
Connection Property................................................................................................................................... 335
DataTypeMap Property
Debug Property................................................................................................................................... 336................................................................................................................................... 336
DetailFields Property................................................................................................................................... 337
Disconnected Property© 2019 Devart

VIII

SQL Server Data Access Components................................................................................................................................... 337
FetchRow s Property................................................................................................................................... 338
FilterSQL Property................................................................................................................................... 338
FinalSQL Property................................................................................................................................... 339
IsQuery Property................................................................................................................................... 340
KeyFields Property................................................................................................................................... 340
MacroCount Property................................................................................................................................... 341
Macros Property................................................................................................................................... 342
MasterFields Property
342
MasterSource ...................................................................................................................................
Property................................................................................................................................... 343
Options Property................................................................................................................................... 345
ParamCheck Property................................................................................................................................... 346
ParamCount Property................................................................................................................................... 346
Params Property................................................................................................................................... 347
ReadOnly Property...................................................................................................................................
347
RefreshOptions
Property348
Row sAffected...................................................................................................................................
PropertySQL Property ................................................................................................................................... 348................................................................................................................................... 349
SQLDelete Property................................................................................................................................... 350
SQLInsert Property................................................................................................................................... 351
SQLLock Property
351
SQLRecCount ...................................................................................................................................
Property................................................................................................................................... 352
SQLRefresh Property................................................................................................................................... 353
SQLUpdate Property................................................................................................................................... 354
UniDirectional Property......................................................................................................................................... 355
Methods................................................................................................................................... 359
AddWhere Method................................................................................................................................... 359
BreakExec Method...................................................................................................................................
360
CreateBlobStream
Method................................................................................................................................... 361
DeleteWhere Method................................................................................................................................... 361
Execute Method................................................................................................................................... 362
Execute Method................................................................................................................................... 362
Execute Method................................................................................................................................... 363
Executing Method................................................................................................................................... 363
Fetched Method................................................................................................................................... 364
Fetching Method................................................................................................................................... 364
FetchingAll Method................................................................................................................................... 365
FindKey Method................................................................................................................................... 365
FindMacro Method................................................................................................................................... 366
FindNearest Method................................................................................................................................... 367
FindParam Method................................................................................................................................... 367
GetDataType Method
368
GetFieldObject...................................................................................................................................
Method...................................................................................................................................
369
GetFieldPrecision
Method................................................................................................................................... 369
GetFieldScale Method...................................................................................................................................
370
GetKeyFieldNames
Method................................................................................................................................... 371
GetOrderBy Method................................................................................................................................... 371
GotoCurrent Method
Lock Method ................................................................................................................................... 372
372
MacroByName...................................................................................................................................
Method373
ParamByName...................................................................................................................................
Method................................................................................................................................... 374
Prepare Method
375
RefreshRecord...................................................................................................................................
Method................................................................................................................................... 375
RestoreSQL Method................................................................................................................................... 376
SaveSQL Method© 2019 Devart

Contents

IX................................................................................................................................... 377
SetOrderBy Method................................................................................................................................... 377
SQLSaved Method
UnLock Method................................................................................................................................... 378......................................................................................................................................... 378
Events................................................................................................................................... 379
AfterExecute Event................................................................................................................................... 380
AfterFetch Event...................................................................................................................................
380
AfterUpdateExecute
Event................................................................................................................................... 381
BeforeFetch Event...................................................................................................................................
381
BeforeUpdateExecute
Event.........................................................................................................................................................
382
TCustomDASQLClass......................................................................................................................................... 382
Members......................................................................................................................................... 384
Properties
386
ChangeCursor...................................................................................................................................
Property................................................................................................................................... 386
Connection Property
Debug Property................................................................................................................................... 387................................................................................................................................... 387
FinalSQL Property................................................................................................................................... 388
MacroCount Property................................................................................................................................... 388
Macros Property................................................................................................................................... 389
ParamCheck Property................................................................................................................................... 390
ParamCount Property................................................................................................................................... 390
Params Property................................................................................................................................... 391
ParamValues Property(Indexer)................................................................................................................................... 392
Prepared Property
392
Row sAffected...................................................................................................................................
PropertySQL Property ................................................................................................................................... 393......................................................................................................................................... 393
Methods................................................................................................................................... 394
Execute Method................................................................................................................................... 394
Execute Method................................................................................................................................... 395
Execute Method................................................................................................................................... 396
Executing Method................................................................................................................................... 396
FindMacro Method................................................................................................................................... 397
FindParam Method
397
MacroByName...................................................................................................................................
Method398
ParamByName...................................................................................................................................
Method................................................................................................................................... 399
Prepare Method................................................................................................................................... 400
UnPrepare Method
400
WaitExecuting ...................................................................................................................................
Method......................................................................................................................................... 401
Events................................................................................................................................... 401
AfterExecute Event.........................................................................................................................................................
402
TCustomDAUpdateSQLClass......................................................................................................................................... 402
Members......................................................................................................................................... 404
Properties................................................................................................................................... 405
DataSet Property................................................................................................................................... 405
DeleteObject Property................................................................................................................................... 406
DeleteSQL Property................................................................................................................................... 406
InsertObject Property................................................................................................................................... 407
InsertSQL Property................................................................................................................................... 407
LockObject Property................................................................................................................................... 408
LockSQL Property................................................................................................................................... 408
ModifyObject Property................................................................................................................................... 409
ModifySQL Property
409
RefreshObject...................................................................................................................................
Property................................................................................................................................... 410
RefreshSQL Property................................................................................................................................... 410
SQL Property(Indexer)© 2019 Devart

X

SQL Server Data Access Components......................................................................................................................................... 411
Methods
Apply Method ................................................................................................................................... 411................................................................................................................................... 412
ExecSQL Method.........................................................................................................................................................
413
TDACondition
Class......................................................................................................................................... 413
Members......................................................................................................................................... 414
Properties................................................................................................................................... 414
Enabled Property
Name Property................................................................................................................................... 415
Value Property................................................................................................................................... 415......................................................................................................................................... 415
Methods
Disable Method................................................................................................................................... 416
Enable Method................................................................................................................................... 416.........................................................................................................................................................
416
TDAConditions
Class......................................................................................................................................... 417
Members......................................................................................................................................... 418
Properties................................................................................................................................... 419
Condition Property(Indexer)................................................................................................................................... 419
Enabled Property................................................................................................................................... 420
Items Property(Indexer)
Text Property ................................................................................................................................... 420................................................................................................................................... 420
WhereSQL Property......................................................................................................................................... 421
Methods
Add Method ................................................................................................................................... 422
Add Method ................................................................................................................................... 422
Add Method ................................................................................................................................... 423
Delete Method ................................................................................................................................... 423
Disable Method................................................................................................................................... 424
Enable Method................................................................................................................................... 424
Find Method ................................................................................................................................... 424
Get Method ................................................................................................................................... 425................................................................................................................................... 425
IndexOf Method................................................................................................................................... 426
Remove Method.........................................................................................................................................................
426
TDAConnectionOptions
Class......................................................................................................................................... 426
Members......................................................................................................................................... 427
Properties...................................................................................................................................
428
Allow ImplicitConnect
Property...................................................................................................................................
429
DefaultSortType
Property...................................................................................................................................
429
DisconnectedMode
Property...................................................................................................................................
430
KeepDesignConnected
Property................................................................................................................................... 430
LocalFailover Property.........................................................................................................................................................
431
TDADataSetOptions
Class......................................................................................................................................... 431
Members......................................................................................................................................... 434
Properties................................................................................................................................... 436
AutoPrepare Property...................................................................................................................................
437
CacheCalcFields
Property...................................................................................................................................
437
CompressBlobMode
Property
438
DefaultValues ...................................................................................................................................
Property................................................................................................................................... 438
DetailDelay Property................................................................................................................................... 439
FieldsOrigin Property................................................................................................................................... 439
FlatBuffers Property...................................................................................................................................
440
InsertAllSetFields
Property...................................................................................................................................
440
LocalMasterDetail
Property................................................................................................................................... 441
LongStrings Property...................................................................................................................................
441
MasterFieldsNullable
Property
441
NumberRange ...................................................................................................................................
Property© 2019 Devart

Contents

XI...................................................................................................................................
442
QueryRecCount
Property................................................................................................................................... 442
QuoteNames Property...................................................................................................................................
443
RemoveOnRefresh
Property443
RequiredFields...................................................................................................................................
Property
444
ReturnParams ...................................................................................................................................
Property...................................................................................................................................
444
SetFieldsReadOnly
Property................................................................................................................................... 445
StrictUpdate Property
445
TrimFixedChar ...................................................................................................................................
Property
446
UpdateAllFields...................................................................................................................................
Property...................................................................................................................................
446
UpdateBatchSize
Property.........................................................................................................................................................
447
TDAEncryption
Class......................................................................................................................................... 447
Members......................................................................................................................................... 447
Properties................................................................................................................................... 448
Encryptor Property
Fields Property................................................................................................................................... 448.........................................................................................................................................................
449
TDAMapRule
Class......................................................................................................................................... 449
Members......................................................................................................................................... 450
Properties
451
DBLengthMax ...................................................................................................................................
Property................................................................................................................................... 452
DBLengthMin Property................................................................................................................................... 452
DBScaleMax Property................................................................................................................................... 453
DBScaleMin Property................................................................................................................................... 453
DBType Property................................................................................................................................... 453
FieldLength Property................................................................................................................................... 454
FieldName Property................................................................................................................................... 454
FieldScale Property................................................................................................................................... 455
FieldType Property................................................................................................................................... 455
IgnoreErrors Property.........................................................................................................................................................
455
TDAMapRules
Class......................................................................................................................................... 456
Members......................................................................................................................................... 456
Properties...................................................................................................................................
457
IgnoreInvalidRules
Property.........................................................................................................................................................
457
TDAMetaData
Class......................................................................................................................................... 458
Members......................................................................................................................................... 462
Properties................................................................................................................................... 463
Connection Property................................................................................................................................... 463
MetaDataKind Property................................................................................................................................... 464
Restrictions Property......................................................................................................................................... 465
Methods...................................................................................................................................
467
GetMetaDataKinds
Method468
GetRestrictions...................................................................................................................................
Method.........................................................................................................................................................
468
TDAParamClass......................................................................................................................................... 469
Members......................................................................................................................................... 471
Properties................................................................................................................................... 472
AsBlob Property................................................................................................................................... 473
AsBlobRef Property................................................................................................................................... 473
AsFloat Property................................................................................................................................... 474
AsInteger Property................................................................................................................................... 474
AsLargeInt Property................................................................................................................................... 475
AsMemo Property................................................................................................................................... 475
AsMemoRef Property...................................................................................................................................
475
AsSQLTimeStamp
Property................................................................................................................................... 476
AsString Property................................................................................................................................... 476
AsWideString Property© 2019 Devart

XII

SQL Server Data Access Components................................................................................................................................... 477
DataType Property
IsNull Property ................................................................................................................................... 477................................................................................................................................... 478
ParamType Property
Size Property ................................................................................................................................... 478
Value Property................................................................................................................................... 479......................................................................................................................................... 479
Methods................................................................................................................................... 480
AssignField Method...................................................................................................................................
480
AssignFieldValue
Method................................................................................................................................... 481
LoadFromFile Method...................................................................................................................................
481
LoadFromStream
Method................................................................................................................................... 482
SetBlobData Method................................................................................................................................... 483
SetBlobData Method................................................................................................................................... 483
SetBlobData Method.........................................................................................................................................................
483
TDAParams
Class......................................................................................................................................... 484
Members......................................................................................................................................... 485
Properties................................................................................................................................... 485
Items Property(Indexer)......................................................................................................................................... 486
Methods................................................................................................................................... 486
FindParam Method
487
ParamByName...................................................................................................................................
Method.........................................................................................................................................................
487
TDATransaction
Class......................................................................................................................................... 488
Members......................................................................................................................................... 489
Properties
Active Property................................................................................................................................... 490...................................................................................................................................
490
DefaultCloseAction
Property......................................................................................................................................... 490
Methods
Commit Method................................................................................................................................... 491................................................................................................................................... 492
Rollback Method...................................................................................................................................
492
StartTransaction
Method......................................................................................................................................... 493
Events................................................................................................................................... 494
OnCommit Event...................................................................................................................................
494
OnCommitRetaining
Event
OnError Event ................................................................................................................................... 495................................................................................................................................... 495
OnRollback Event...................................................................................................................................
496
OnRollbackRetaining
Event......................................................................................................................................................... 497
TMacro Class......................................................................................................................................... 497
Members......................................................................................................................................... 498
Properties
Active Property................................................................................................................................... 499................................................................................................................................... 499
AsDateTime Property................................................................................................................................... 500
AsFloat Property................................................................................................................................... 500
AsInteger Property................................................................................................................................... 501
AsString Property
Name Property................................................................................................................................... 501
Value Property................................................................................................................................... 501
502
TMacros .........................................................................................................................................................
Class......................................................................................................................................... 502
Members......................................................................................................................................... 503
Properties................................................................................................................................... 503
Items Property(Indexer)......................................................................................................................................... 504
Methods
505
AssignValues ...................................................................................................................................
MethodExpand Method................................................................................................................................... 505................................................................................................................................... 506
FindMacro Method
IsEqual Method................................................................................................................................... 506© 2019 Devart

Contents

XIII

507
MacroByName...................................................................................................................................
MethodScan Method ................................................................................................................................... 507.........................................................................................................................................................
508
TPoolingOptions
Class......................................................................................................................................... 508
Members......................................................................................................................................... 509
Properties...................................................................................................................................
510
ConnectionLifetime
Property................................................................................................................................... 510
MaxPoolSize Property................................................................................................................................... 511
MinPoolSize Property................................................................................................................................... 511
Validate Property.........................................................................................................................................................
511
TSmartFetchOptions
Class......................................................................................................................................... 512
Members......................................................................................................................................... 512
Properties................................................................................................................................... 513
Enabled Property................................................................................................................................... 513
LiveBlock Property...................................................................................................................................
514
PrefetchedFields
Property...................................................................................................................................
514
SQLGetKeyValues
Property.......................................................................................................................................................... 515
Types.........................................................................................................................................................
516
TAfterExecuteEvent
Procedure Reference.........................................................................................................................................................
516
TAfterFetchEvent
Procedure Reference.........................................................................................................................................................
517
TBeforeFetchEvent
Procedure Reference.........................................................................................................................................................
517
TConnectionLostEvent
Procedure Reference.........................................................................................................................................................
518
TDAConnectionErrorEvent
Procedure Reference.........................................................................................................................................................
518
TDATransactionErrorEvent
Procedure Reference.........................................................................................................................................................
519
TRefreshOptions
Set.........................................................................................................................................................
519
TUpdateExecuteEvent
Procedure Reference.......................................................................................................................................................... 520
Enum erations
520
TLabelSet.........................................................................................................................................................
Enumeration.........................................................................................................................................................
521
TRefreshOption
Enumeration.........................................................................................................................................................
521
TRetryMode
Enumeration
Variables .......................................................................................................................................................... 522.........................................................................................................................................................
522
BaseSQLOldBehavior
Variable.........................................................................................................................................................
523
ChangeCursor
Variable.........................................................................................................................................................
523
SQLGeneratorCompatibility
Variable

11 MemData................................................................................................................................... 524.......................................................................................................................................................... 525
Classes526
TAttribute.........................................................................................................................................................
Class.........................................................................................................................................
526
Members.........................................................................................................................................
527
Properties...................................................................................................................................
528
AttributeNo Property...................................................................................................................................
529
DataSize Property...................................................................................................................................
529
DataType Property...................................................................................................................................
529
Length Property...................................................................................................................................
530
ObjectType Property...................................................................................................................................
530
Offset Property...................................................................................................................................
531
Ow ner Property...................................................................................................................................
531
Scale Property...................................................................................................................................
532
Size Property.........................................................................................................................................................
532
TBlob Class.........................................................................................................................................
533
Members.........................................................................................................................................
534
Properties...................................................................................................................................
535
AsString Property...................................................................................................................................
535
AsWideString Property...................................................................................................................................
536
IsUnicode Property...................................................................................................................................
536
Size Property© 2019 Devart

XIV

SQL Server Data Access Components......................................................................................................................................... 537
Methods
Assign Method................................................................................................................................... 538
Clear Method ................................................................................................................................... 538................................................................................................................................... 539
LoadFromFile Method...................................................................................................................................
539
LoadFromStream
MethodRead Method ................................................................................................................................... 540................................................................................................................................... 541
SaveToFile Method
541
SaveToStream...................................................................................................................................
Method................................................................................................................................... 542
Truncate Method
Write Method ................................................................................................................................... 542.........................................................................................................................................................
543
TCompressedBlob
Class......................................................................................................................................... 544
Members......................................................................................................................................... 546
Properties................................................................................................................................... 546
Compressed Property...................................................................................................................................
547
CompressedSize
Property.........................................................................................................................................................
547
TDBObjectClass......................................................................................................................................... 548
Members.........................................................................................................................................................
548
TMemData
Class......................................................................................................................................... 549
Members.........................................................................................................................................................
549
TObjectType
Class......................................................................................................................................... 549
Members......................................................................................................................................... 550
Properties
551
AttributeCount...................................................................................................................................
Property................................................................................................................................... 551
Attributes Property(Indexer)................................................................................................................................... 552
DataType Property
Size Property ................................................................................................................................... 552......................................................................................................................................... 553
Methods................................................................................................................................... 554
FindAttribute Method.........................................................................................................................................................
554
TSharedObject
Class......................................................................................................................................... 555
Members......................................................................................................................................... 555
Properties................................................................................................................................... 556
RefCount Property......................................................................................................................................... 556
Methods................................................................................................................................... 557
AddRef Method................................................................................................................................... 557
Release Method.......................................................................................................................................................... 558
Types.........................................................................................................................................................
558
TLocateExOptions
Set.........................................................................................................................................................
559
TUpdateRecKinds
Set.......................................................................................................................................................... 559
Enum erations.........................................................................................................................................................
560
TCompressBlobMode
Enumeration.........................................................................................................................................................
561
TConnLostCause
Enumeration.........................................................................................................................................................
561
TDANumericType
Enumeration.........................................................................................................................................................
562
TLocateExOption
Enumeration.........................................................................................................................................................
563
TSortType
Enumeration.........................................................................................................................................................
563
TUpdateRecKind
Enumeration

12 MemDS................................................................................................................................... 564.......................................................................................................................................................... 564
Classes.........................................................................................................................................................
565
TMemDataSet
Class.........................................................................................................................................
565
Members.........................................................................................................................................
568
Properties...................................................................................................................................
569
CachedUpdates Property...................................................................................................................................
570
IndexFieldNames Property...................................................................................................................................
571
KeyExclusive Property...................................................................................................................................
572
LocalConstraints Property© 2019 Devart

Contents

XV................................................................................................................................... 573
LocalUpdate Property................................................................................................................................... 573
Prepared Property................................................................................................................................... 574
Ranged Property...................................................................................................................................
574
UpdateRecordTypes
Property...................................................................................................................................
575
UpdatesPending
Property......................................................................................................................................... 575
Methods................................................................................................................................... 577
ApplyRange Method
578
ApplyUpdates ...................................................................................................................................
Method579
ApplyUpdates ...................................................................................................................................
Method580
ApplyUpdates ...................................................................................................................................
Method................................................................................................................................... 581
CancelRange Method581
CancelUpdates...................................................................................................................................
Method582
CommitUpdates...................................................................................................................................
Method................................................................................................................................... 583
DeferredPost Method................................................................................................................................... 583
EditRangeEnd Method
584
EditRangeStart...................................................................................................................................
Method................................................................................................................................... 585
GetBlob Method................................................................................................................................... 585
GetBlob Method................................................................................................................................... 586
GetBlob Method
Locate Method................................................................................................................................... 586
Locate Method................................................................................................................................... 587
Locate Method................................................................................................................................... 587................................................................................................................................... 588
LocateEx Method................................................................................................................................... 589
LocateEx Method................................................................................................................................... 590
LocateEx Method................................................................................................................................... 591
Prepare Method...................................................................................................................................
591
RestoreUpdates
Method592
RevertRecord ...................................................................................................................................
Method................................................................................................................................... 592
SaveToXML Method................................................................................................................................... 593
SaveToXML Method................................................................................................................................... 593
SaveToXML Method................................................................................................................................... 594
SetRange Method................................................................................................................................... 595
SetRangeEnd Method
596
SetRangeStart...................................................................................................................................
Method................................................................................................................................... 597
UnPrepare Method................................................................................................................................... 597
UpdateResult Method................................................................................................................................... 598
UpdateStatus Method......................................................................................................................................... 598
Events599
OnUpdateError...................................................................................................................................
Event...................................................................................................................................
600
OnUpdateRecord
Event
Variables .......................................................................................................................................................... 601.........................................................................................................................................................
601
DoNotRaiseExcetionOnUaFail
Variable.........................................................................................................................................................
601
SendDataSetChangeEventAfterOpen
Variable

13 MSAccess................................................................................................................................... 602.......................................................................................................................................................... 605
Classes.........................................................................................................................................................
608
TCustomMSConnection
Class.........................................................................................................................................
608
Members.........................................................................................................................................
611
Properties...................................................................................................................................
613
ClientVersion Property...................................................................................................................................
613
Database Property...................................................................................................................................
614
IsolationLevel Property...................................................................................................................................
615
Options Property...................................................................................................................................
615
ServerVersion Property.........................................................................................................................................
616
Methods© 2019 Devart

XVI

SQL Server Data Access Components
618
AssignConnect...................................................................................................................................
Method................................................................................................................................... 618
CreateSQL Method
619
OpenDatasets ...................................................................................................................................
Method.........................................................................................................................................................
619
TCustomMSConnectionOptions
Class......................................................................................................................................... 620
Members......................................................................................................................................... 621
Properties................................................................................................................................... 623
Encrypt Property................................................................................................................................... 623
NumericType Property................................................................................................................................... 624
Provider Property...................................................................................................................................
624
QuotedIdentifier
Property...................................................................................................................................
625
UseWideMemos
Property.........................................................................................................................................................
625
TCustomMSDataSet
Class......................................................................................................................................... 626
Members......................................................................................................................................... 635
Properties...................................................................................................................................
639
ChangeNotification
Property...................................................................................................................................
640
CommandTimeout
Property................................................................................................................................... 641
Connection Property................................................................................................................................... 642
CursorType Property................................................................................................................................... 642
Encryption Property................................................................................................................................... 643
FetchAll Property................................................................................................................................... 644
Options Property................................................................................................................................... 646
Params Property................................................................................................................................... 647
SmartFetch Property................................................................................................................................... 647
UpdateObject Property......................................................................................................................................... 648
Methods
652
CreateProcCall...................................................................................................................................
Method................................................................................................................................... 653
FindParam Method...................................................................................................................................
653
GetFileStreamForField
MethodLock Method ................................................................................................................................... 655
Lock Method ................................................................................................................................... 655
Lock Method ................................................................................................................................... 656................................................................................................................................... 657
LockTable Method................................................................................................................................... 657
OpenNext Method
658
ParamByName...................................................................................................................................
Method................................................................................................................................... 659
RefreshQuick Method......................................................................................................................................... 660
Events...................................................................................................................................
661
AfterUpdateExecute
Event...................................................................................................................................
662
BeforeUpdateExecute
Event.........................................................................................................................................................
662
TCustomMSStoredProc
Class......................................................................................................................................... 663
Members......................................................................................................................................... 672
Properties...................................................................................................................................
677
StoredProcName
Property
677
UpdatingTable ...................................................................................................................................
Property......................................................................................................................................... 678
Methods................................................................................................................................... 682
ExecProc Method................................................................................................................................... 683
PrepareSQL Method.........................................................................................................................................................
683
TCustomMSTable
Class......................................................................................................................................... 684
Members......................................................................................................................................... 693
Properties................................................................................................................................... 698
OrderFields Property................................................................................................................................... 698
TableName Property......................................................................................................................................... 699
Methods................................................................................................................................... 703
PrepareSQL Method.........................................................................................................................................................
704
TMSChangeNotification
Class© 2019 Devart

Contents

XVII......................................................................................................................................... 705
Members......................................................................................................................................... 705
Properties................................................................................................................................... 706
Enabled Property................................................................................................................................... 706
Service Property................................................................................................................................... 707
TimeOut Property......................................................................................................................................... 708
Events................................................................................................................................... 708
OnChange Event.........................................................................................................................................................
709
TMSConnection
Class......................................................................................................................................... 710
Members......................................................................................................................................... 713
Properties
715
Authentication...................................................................................................................................
Property...................................................................................................................................
715
ConnectionTimeout
Property................................................................................................................................... 716
Options Property
Port Property ................................................................................................................................... 717......................................................................................................................................... 718
Methods
720
ChangePassw...................................................................................................................................
ord Method......................................................................................................................................... 720
Events...................................................................................................................................
721
OnInfoMessage
Event.........................................................................................................................................................
722
TMSConnectionOptions
Class......................................................................................................................................... 722
Members......................................................................................................................................... 725
Properties...................................................................................................................................
728
ApplicationIntent
Property...................................................................................................................................
728
ApplicationName
Property
729
AutoTranslate ...................................................................................................................................
Property...................................................................................................................................
729
DefaultLockTimeout
Property................................................................................................................................... 730
Encrypt Property
730
FailoverPartner...................................................................................................................................
Property...................................................................................................................................
730
ForceCreateDatabase
Property................................................................................................................................... 731
InitialFileName Property................................................................................................................................... 732
IPVersion Property................................................................................................................................... 732
Language Property...................................................................................................................................
733
MultipleActiveResultSets
Property...................................................................................................................................
733
MultipleConnections
Property...................................................................................................................................
734
NativeClientVersion
Property
734
Netw orkLibrary...................................................................................................................................
Property................................................................................................................................... 735
PacketSize Property...................................................................................................................................
735
PersistSecurityInfo
Property................................................................................................................................... 736
Provider Property...................................................................................................................................
736
TrustServerCertificate
Property................................................................................................................................... 737
WorkstationID Property.........................................................................................................................................................
737
TMSDataSetOptions
Class......................................................................................................................................... 737
Members......................................................................................................................................... 742
Properties...................................................................................................................................
746
AllFieldsEditable
Property................................................................................................................................... 747
AutoPrepare Property................................................................................................................................... 747
AutoRefresh Property...................................................................................................................................
748
AutoRefreshInterval
Property...................................................................................................................................
748
CheckRow Version
Property
749
CursorUpdate ...................................................................................................................................
Property
749
DefaultValues ...................................................................................................................................
Property...................................................................................................................................
750
DescribeParams
Property...................................................................................................................................
750
DisableMultipleResults
Property................................................................................................................................... 751
DMLRefresh Property................................................................................................................................... 751
EnableBCD Property© 2019 Devart

XVIIISQL Server Data Access Components................................................................................................................................... 752
FullRefresh Property...................................................................................................................................
752
HideSystemUniqueFields
Property...................................................................................................................................
753
LastIdentityValueFunction
Property................................................................................................................................... 753
LongStrings Property................................................................................................................................... 754
NonBlocking Property
754
NumberRange ...................................................................................................................................
Property...................................................................................................................................
755
PrepareUpdateSQL
Property................................................................................................................................... 755
QueryIdentity Property...................................................................................................................................
756
QueryRecCount
Property................................................................................................................................... 756
QuoteNames Property...................................................................................................................................
757
ReflectChangeNotify
Property...................................................................................................................................
757
RemoveOnRefresh
Property
758
RequiredFields...................................................................................................................................
Property
758
ReturnParams ...................................................................................................................................
Property...................................................................................................................................
759
SetEmptyStrToNull
Property................................................................................................................................... 759
StrictUpdate Property
760
TrimFixedChar ...................................................................................................................................
Property................................................................................................................................... 760
TrimVarChar Property
761
UniqueRecords...................................................................................................................................
Property.........................................................................................................................................................
761
TMSDataSourceClass......................................................................................................................................... 762
Members.........................................................................................................................................................
762
TMSEncryptor
Class......................................................................................................................................... 763
Members.........................................................................................................................................................
763
TMSFileStreamClass......................................................................................................................................... 764
Members......................................................................................................................................... 764
Methods
Close Method ................................................................................................................................... 765
Flush Method ................................................................................................................................... 765.........................................................................................................................................................
766
TMSMetadataClass......................................................................................................................................... 767
Members......................................................................................................................................... 772
Properties................................................................................................................................... 775
AssemblyID Property...................................................................................................................................
776
AssemblyName
Property................................................................................................................................... 777
ColumnName Property...................................................................................................................................
778
ConstraintName
Property
778
DatabaseName...................................................................................................................................
Property................................................................................................................................... 779
IndexName Property................................................................................................................................... 780
LinkedServer Property................................................................................................................................... 781
ObjectType Property...................................................................................................................................
781
ReferencedAssemblyID
Property...................................................................................................................................
782
SchemaCollectionName
Property................................................................................................................................... 783
SchemaName Property...................................................................................................................................
784
StoredProcName
Property................................................................................................................................... 784
TableName Property...................................................................................................................................
785
TargetNamespaceURI
Property................................................................................................................................... 786
UDTName Property.........................................................................................................................................................
787
TMSParamClass......................................................................................................................................... 788
Members......................................................................................................................................... 789
Properties................................................................................................................................... 791
AsTable Property...................................................................................................................................
791
TableTypeName
Property.........................................................................................................................................................
792
TMSParams
Class......................................................................................................................................... 792
Members.........................................................................................................................................................
793
TMSQueryClass© 2019 Devart

Contents

XIX......................................................................................................................................... 794
Members......................................................................................................................................... 803
Properties................................................................................................................................... 808
FetchAll Property................................................................................................................................... 808
LockMode Property
809
UpdatingTable ...................................................................................................................................
Property
810
TMSSQL .........................................................................................................................................................
Class......................................................................................................................................... 810
Members......................................................................................................................................... 813
Properties...................................................................................................................................
815
CommandTimeout
Property................................................................................................................................... 816
Connection Property...................................................................................................................................
817
DescribeParams
Property................................................................................................................................... 817
NonBlocking Property................................................................................................................................... 818
Params Property
818
PermitPrepare ...................................................................................................................................
Property......................................................................................................................................... 819
Methods...................................................................................................................................
820
ExecuteForXML
Method...................................................................................................................................
820
ExecuteForXML
Method...................................................................................................................................
821
ExecuteForXML
Method................................................................................................................................... 821
FindParam Method
822
ParamByName...................................................................................................................................
Method.........................................................................................................................................................
823
TMSStoredProc
Class......................................................................................................................................... 824
Members......................................................................................................................................... 833
Properties................................................................................................................................... 838
LockMode Property...................................................................................................................................
838
StoredProcName
Property
839
TMSTable.........................................................................................................................................................
Class......................................................................................................................................... 840
Members......................................................................................................................................... 849
Properties................................................................................................................................... 853
FetchAll Property................................................................................................................................... 854
LockMode Property................................................................................................................................... 854
OrderFields Property................................................................................................................................... 855
TableName Property.........................................................................................................................................................
855
TMSTableData
Class......................................................................................................................................... 856
Members......................................................................................................................................... 859
Properties................................................................................................................................... 861
Connection Property
Table Property................................................................................................................................... 861...................................................................................................................................
862
TableTypeName
Property.........................................................................................................................................................
862
TMSUDTField
Class......................................................................................................................................... 863
Members......................................................................................................................................... 863
Properties...................................................................................................................................
864
AssemblyTypename
Property................................................................................................................................... 865
AsUDT Property...................................................................................................................................
866
UDTCatalogname
Property................................................................................................................................... 866
UDTName Property...................................................................................................................................
867
UDTSchemaname
Property.........................................................................................................................................................
867
TMSUpdateSQLClass......................................................................................................................................... 868
Members.........................................................................................................................................................
869
TMSXMLField
Class......................................................................................................................................... 869
Members......................................................................................................................................... 870
Properties...................................................................................................................................
870
SchemaCollection
Property
Typed Property................................................................................................................................... 871
XML Property ................................................................................................................................... 872© 2019 Devart

XX

SQL Server Data Access Components.......................................................................................................................................................... 872
Types.........................................................................................................................................................
872
TMSChangeNotificationEvent
Procedure Reference.........................................................................................................................................................
873
TMSUpdateExecuteEvent
Procedure Reference.......................................................................................................................................................... 874
Enum erations.........................................................................................................................................................
874
TIsolationLevel
Enumeration.........................................................................................................................................................
875
TMSLockType
Enumeration.........................................................................................................................................................
876
TMSNotificationInfo
Enumeration.........................................................................................................................................................
877
TMSNotificationSource
Enumeration.........................................................................................................................................................
878
TMSNotificationType
Enumeration.........................................................................................................................................................
878
TMSObjectType
Enumeration
Variables .......................................................................................................................................................... 881.........................................................................................................................................................
881__UseUpdateOptimization
Variable
Constants .......................................................................................................................................................... 882.........................................................................................................................................................
882
SDACVersion
Constant

14 MSClasses................................................................................................................................... 882.......................................................................................................................................................... 883
Enum erations.........................................................................................................................................................
884
TApplicationIntent
Enumeration.........................................................................................................................................................
885
TCompactCommitMode Enumeration.........................................................................................................................................................
885
TCompactVersion Enumeration.........................................................................................................................................................
886
TMSAuthentication Enumeration.........................................................................................................................................................
886
TMSCursorType Enumeration.........................................................................................................................................................
888
TMSInitMode Enumeration.........................................................................................................................................................
888
TMSLastIdentityValueFunction Enumeration.........................................................................................................................................................
889
TMSProvider Enumeration.........................................................................................................................................................
890
TNativeClientVersion Enumeration

15 MSCompactConnection................................................................................................................................... 890.......................................................................................................................................................... 891
Classes.........................................................................................................................................................
891
TMSCompactConnection
Class......................................................................................................................................... 892
Members......................................................................................................................................... 895
Properties................................................................................................................................... 897
Database Property................................................................................................................................... 898
InitMode Property
898
LockEscalation...................................................................................................................................
Property................................................................................................................................... 899
LockTimeout Property................................................................................................................................... 899
Options Property...................................................................................................................................
900
TransactionCommitMode
Property.........................................................................................................................................................
901
TMSCompactConnectionOptions
Class......................................................................................................................................... 901
Members......................................................................................................................................... 903
Properties...................................................................................................................................
906
AutoShrinkThreshold
Property...................................................................................................................................
906
CompactVersion
Property...................................................................................................................................
906
DefaultLockEscalation
Property...................................................................................................................................
907
DefaultLockTimeout
Property................................................................................................................................... 907
FlushInterval Property...................................................................................................................................
908
ForceCreateDatabase
Property
909
LocaleIdentifier...................................................................................................................................
Property
909
MaxBufferSize...................................................................................................................................
Property...................................................................................................................................
910
MaxDatabaseSize
Property...................................................................................................................................
910
TempFileDirectory
Property...................................................................................................................................
910
TempFileMaxSize
Property

16 MSConnectionPool................................................................................................................................... 911.......................................................................................................................................................... 911
Classes.........................................................................................................................................................
912
TMSConnectionPoolManager
Class© 2019 Devart

Contents
Members

XXI......................................................................................................................................... 912

17 MSDump................................................................................................................................... 912.......................................................................................................................................................... 913
Classes
913
TMSDump.........................................................................................................................................................
Class.........................................................................................................................................
914
Members.........................................................................................................................................
916
Properties...................................................................................................................................
916
Connection Property...................................................................................................................................
917
Options Property.........................................................................................................................................................
917
TMSDumpOptions Class.........................................................................................................................................
918
Members.........................................................................................................................................
919
Properties...................................................................................................................................
920
DisableConstraints Property...................................................................................................................................
920
IdentityInsert Property

18 MSLoader................................................................................................................................... 921.......................................................................................................................................................... 921
Classes.........................................................................................................................................................
922
TMSColumnClass......................................................................................................................................... 922
Members......................................................................................................................................... 923
Properties................................................................................................................................... 924
Precision Property
Scale Property................................................................................................................................... 924
Size Property ................................................................................................................................... 925.........................................................................................................................................................
925
TMSLoaderClass......................................................................................................................................... 926
Members......................................................................................................................................... 927
Properties................................................................................................................................... 928
KeepIdentity Property................................................................................................................................... 928
KeepNulls Property................................................................................................................................... 929
Options Property......................................................................................................................................... 930
Events...................................................................................................................................
930
OnGetColumnData
Event................................................................................................................................... 931
OnPutData Event.........................................................................................................................................................
932
TMSLoaderOptions
Class......................................................................................................................................... 932
Members......................................................................................................................................... 933
Properties...................................................................................................................................
934
CheckConstraints
Property................................................................................................................................... 934
FireTrigger Property...................................................................................................................................
935
KilobytesPerBatch
Property................................................................................................................................... 935
LockTable Property
935
Row sPerBatch...................................................................................................................................
Property.......................................................................................................................................................... 936
Types.........................................................................................................................................................
936
TMSPutDataEvent
Procedure Reference

19 MSScript................................................................................................................................... 937.......................................................................................................................................................... 937
Classes.........................................................................................................................................................
937
TMSScript
Class......................................................................................................................................... 938
Members......................................................................................................................................... 940
Properties................................................................................................................................... 941
Connection Property................................................................................................................................... 942
DataSet Property...................................................................................................................................
942
UseOptimization
Property

20 MSServiceBroker................................................................................................................................... 943.......................................................................................................................................................... 943
Classes.........................................................................................................................................................
944
TMSConversation
Class......................................................................................................................................... 945
Members......................................................................................................................................... 946
Properties© 2019 Devart

XXII

SQL Server Data Access Components
946
ContractName ...................................................................................................................................
Property................................................................................................................................... 947
FarService Property................................................................................................................................... 947
GroupId Property................................................................................................................................... 948
Handle Property................................................................................................................................... 949
IsInitiator Property
949
ServiceBroker ...................................................................................................................................
Property......................................................................................................................................... 950
Methods................................................................................................................................... 950
BeginTimer Method...................................................................................................................................
951
EndConversation
Method...................................................................................................................................
952
EndConversationWithError
Method...................................................................................................................................
952
GetTransmissionStatus
MethodSend Method ................................................................................................................................... 953
Send Method ................................................................................................................................... 953
Send Method ................................................................................................................................... 954................................................................................................................................... 955
SendEmpty Method.........................................................................................................................................................
956
TMSMessage
Class......................................................................................................................................... 956
Members......................................................................................................................................... 957
Properties................................................................................................................................... 958
AsBytes Property................................................................................................................................... 959
AsString Property................................................................................................................................... 959
AsWideString Property................................................................................................................................... 960
Conversation Property................................................................................................................................... 960
IsEmpty Property...................................................................................................................................
961
MessageSequenceNumber
Property
961
MessageType ...................................................................................................................................
Property
962
QueuingOrder ...................................................................................................................................
Property................................................................................................................................... 962
Validation Property.........................................................................................................................................................
963
TMSServiceBroker
Class......................................................................................................................................... 964
Members......................................................................................................................................... 965
Properties...................................................................................................................................
967
AsyncNotification
Property................................................................................................................................... 967
Connection Property...................................................................................................................................
968
ConversationCount
Property
968
Conversations...................................................................................................................................
Property(Indexer)...................................................................................................................................
969
CurrentMessage
Property................................................................................................................................... 970
FetchRow s Property................................................................................................................................... 970
Queue Property................................................................................................................................... 971
Service Property................................................................................................................................... 972
WaitTimeout Property......................................................................................................................................... 972
Methods................................................................................................................................... 973
BeginDialog Method................................................................................................................................... 974
BeginDialog Method................................................................................................................................... 975
BeginDialog Method...................................................................................................................................
976
CreateServerObjects
Method...................................................................................................................................
977
DropServerObjects
Method...................................................................................................................................
977
GetContractNames
Method...................................................................................................................................
978
GetMessageTypeNames
Method...................................................................................................................................
979
GetQueueNames
Method...................................................................................................................................
979
GetServiceNames
Method................................................................................................................................... 980
Receive Method......................................................................................................................................... 981
Events...................................................................................................................................
982
OnBeginConversation
Event...................................................................................................................................
982
OnEndConversation
Event................................................................................................................................... 983
OnMessage Event© 2019 Devart

Contents

XXIII.......................................................................................................................................................... 984
Enum erations.........................................................................................................................................................
984
TMSMessageValidation
Enumeration

21 MSSQLMonitor................................................................................................................................... 984.......................................................................................................................................................... 985
Classes.........................................................................................................................................................
985
TMSSQLMonitor
Class.........................................................................................................................................
986
Members

22 MSTransaction................................................................................................................................... 987.......................................................................................................................................................... 987
Classes.........................................................................................................................................................
987
TMSTransaction
Class......................................................................................................................................... 988
Members......................................................................................................................................... 989
Properties...................................................................................................................................
989
ConnectionsCount
Property................................................................................................................................... 990
IsolationLevel Property......................................................................................................................................... 990
Methods991
AddConnection...................................................................................................................................
Method...................................................................................................................................
992
RemoveConnection
Method23 OLEDBAccess................................................................................................................................... 992.......................................................................................................................................................... 993
Classes993
EMSError.........................................................................................................................................................
Class......................................................................................................................................... 994
Members......................................................................................................................................... 995
Properties................................................................................................................................... 996
LastMessage Property................................................................................................................................... 996
LineNumber Property...................................................................................................................................
997
MSSQLErrorCode
Property................................................................................................................................... 997
ProcName Property................................................................................................................................... 998
ServerName Property
998
SeverityClass ...................................................................................................................................
Property
State Property ................................................................................................................................... 998.........................................................................................................................................................
999
EOLEDBError
Class......................................................................................................................................... 1000
Members......................................................................................................................................... 1000
Properties................................................................................................................................... 1001
ErrorCount Property................................................................................................................................... 1001
Errors Property(Indexer)
1002
MessageWide...................................................................................................................................
Property...................................................................................................................................
1002
OLEDBErrorCode
Property
Variables .......................................................................................................................................................... 1003.........................................................................................................................................................
1003
ParamsInfoOldBehavior
Variable

24 SdacVcl................................................................................................................................... 1004
Classes .......................................................................................................................................................... 1004.........................................................................................................................................................
1005
TMSConnectDialog
Class......................................................................................................................................... 1005
Members......................................................................................................................................... 1007
Properties................................................................................................................................... 1008
Connection Property......................................................................................................................................... 1008
Methods
1009
GetServerList...................................................................................................................................
Method25 VirtualDataSet................................................................................................................................... 1009
Classes .......................................................................................................................................................... 1010.........................................................................................................................................................
1011
TCustomVirtualDataSet
Class......................................................................................................................................... 1011
Members.........................................................................................................................................................
1014
TVirtualDataSet
Class......................................................................................................................................... 1014
Members.......................................................................................................................................................... 1017
Types
© 2019 Devart

XXIV

SQL Server Data Access Components.........................................................................................................................................................
1018
TOnDeleteRecordEvent
Procedure Reference.........................................................................................................................................................
1018
TOnGetFieldValueEvent
Procedure Reference.........................................................................................................................................................
1019
TOnGetRecordCountEvent
Procedure Reference.........................................................................................................................................................
1020
TOnModifyRecordEvent
Procedure Reference

26 VirtualTable................................................................................................................................... 1020
Classes .......................................................................................................................................................... 1020.........................................................................................................................................................
1021
TVirtualTable
Class.........................................................................................................................................
1021
Members.........................................................................................................................................
1024
Properties...................................................................................................................................
1026
DefaultSortType Property.........................................................................................................................................
1026
Methods...................................................................................................................................
1028
Assign Method...................................................................................................................................
1029
LoadFromFile Method© 2019 Devart

What's New

1

What's New

26-Nov-2019 New Features in SDAC 9.1:
Android 64-bit is supported
Lazarus 2.0.6 is supported
TLS 1.2 support in the Direct mode is added
Now Trial edition for macOS and Linux is fully functional
The connection option MultiSubnetFailover for the MSOLEDB provider is added
Use of the Server property that contains Port in the Direct mode is added
Updating data after invoking the Refresh method is fixed

22-Jul-2019 New Features in SDAC 9.0:
macOS 64-bit is supported
Release 2 for RAD Studio 10.3 Rio, Delphi 10.3 Rio, and C++Builder 10.3 Rio is now
required24-Jun-2019 New Features in SDAC 8.3:
Lazarus 2.0.2 is supported
Working with multiple threads sharing a single connection is supported
The DefaultSortType property for TVirtualTable is added
Performance of the SaveToFile/LoadFromFile methods of TVirtualTable is significantly
increased

26-Nov-2018 New Features in SDAC 8.2:
RAD Studio 10.3 Rio is supported
TfrxSDACDatabase.DefaultLockTimeout property is added
QuoteNames option in TMSLoader to escape field names is added
Support of UPPER and LOWER functions for Unified SQL is added

09-Jul-2018 New Features in SDAC 8.1:
Lazarus 1.8.4 is supported
MARS in TDS is supported
NonBlocking mode in TDS is supported
Query notifications in TDS are supported
TCustomMSDataSet.CommandTimeout property in TDS is supported© 2019 Devart

1

2

SQL Server Data Access Components

Performance of batch operations is improved
Demo projects for IntraWeb 14 are added

05-Apr-2017 New Features in SDAC 8.0:
RAD Studio 10.2 Tokyo is supported
Linux in RAD Studio 10.2 Tokyo is supported
Lazarus 1.6.4 and Free Pascal 3.0.2 is supported

25-Apr-16 New Features in SDAC 7.3:
RAD Studio 10.1 Berlin is supported
Lazarus 1.6 and FPC 3.0.0 is supported
Support for the BETWEEN statement in TDADataSet.Filter is added
The TMSLoaderOptions.FireTrigger property is added
SmartFetch mode in Disconnected mode is supported
Data Type Mapping performance is improved
Performance of TDALoader on loading data from TDataSet is improved

09-Sep-15 New Features in SDAC 7.2:
RAD Studio 10 Seattle is supported
Now Trial for Win64 is a fully functional Professional Edition
INSERT, UPDATE and DELETE batch operations are supported

14-Apr-15 New Features in SDAC 7.1:
RAD Studio XE8 is supported
AppMethod is supported
Direct mode in Lazarus is supported
Now the Direct mode is supplied as source code
Performance of connection establishing in the Direct mode is improved

25-Nov-14 New Features in SDAC 7.01:
Direct Mode is supported
Mac OS X is supported
iOS is supported
Android is supported

15-Sep-14 New Features in SDAC 6.11:© 2019 Devart

What's New

3

RAD Studio XE7 is supported
Lazarus 1.2.4 is supported
The TCustomDADataSet.GetKeyFieldNames method is added
The ConstraintColumns metadata kind for the TMSMetadata component is added

29-Apr-14 New Features in SDAC 6.10:
RAD Studio XE6 is supported
Lazarus 1.2.2 and FPC 2.6.4 is supported
SQL Server 2014 is supported
SmartFetch mode for TDataSet descendants is added
The TMSDataSetOptions.MasterFieldsNullable property is added
Now update queries inside TDataSet descendants have correct owner

25-Dec-13 New Features in SDAC 6.9:
RAD Studio XE5 Update 2 is now required
Now .obj and .o files are supplied for C++Builder
Compatibility of migrating floating-point fields from other components is improved
The TMSConnection.AutoCommit property is added
Default values of UNIQUEIDENTIFIER fields without curly brackets are supported

18-Sep-13 New Features in SDAC 6.8:
RAD Studio XE5 is supported
Lazarus 1.0.12 is supported
Performance is improved
Automatic checking for new versions is added
Flexible management of conditions in the WHERE clause is added
The possibility to use conditions is added
Support of the IN keyword in the TDataSet.Filter property is added
Like operator behaviour when used in the Filter property is now similar to TClientDataSet
The possibility to use ranges is added
The Ping method for the TMSConnection component is added
The AllowImplicitConnect option for the TMSConnection component is added
The ForceCreateDatabase option for the TMSConnection is added
The ApplicationIntent option for the TMSConnection is added
The SQLRecCount property for the TMSQuery and TMSStoredProc components is added
The ScanParams property for the TMSScript component is added© 2019 Devart

4

SQL Server Data Access Components

The RowsAffected property for the TMSScript component is added

25-Apr-13 New Features in SDAC 6.7:
Rad Studio XE4 is supported
FPC 2.6.2 and Lazarus 1.0.8 are supported
Connection string support is added
Now the TCustomMSDataSet.Options.UniqueRecords property is set to True by default
The TCustomMSDataSet.Options.HideSystemUniqueFields property is added
Possibility to encrypt entire tables and datasets is added
Possibility to determine if data in a field is encrypted is added
Support for TimeStamp, Single and Extended fields in VirtualTable is added

12-Dec-12 New Features in SDAC 6.6:
Rad Studio XE3 Update 1 is now required
C++Builder 64-bit for Windows is supported
TMSConnection.Port property that allows specifying the port number for connection is
added

05-Sep-12 New Features in SDAC 6.5:
Rad Studio XE3 is supported
Windows 8 is supported

21-Jun-12 New Features in SDAC 6.2:
Update 4 Hotfix 1 for RAD Studio XE2, Delphi XE2, and C++Builder XE2 is now required
Data Type Mapping support is added
Data encryption in a client application is added
The TMSEncryptor component for data encryption is added
Calling of the TCustomDASQL.BeforeExecute event is added

23-Nov-11 New Features in SDAC 6.1:
Update 4 for RAD Studio XE2, Delphi XE2, and C++Builder XE2 is now required
FireMonkey support is improved
Lazarus 0.9.30.4 and FPC 2.6.0 are supported

15-Sep-11 New Features in SQL Server Data Access
Components 6.00:© 2019 Devart

What's New

5

Embarcadero RAD Studio XE2 is supported
Application development for 64-bit Windows is supported
FireMonkey application development platform is supported
Support of master/detail relationship for TVirtualTable is added
OnProgress event in TVirtualTable is added
TDADataSetOptions.SetEmptyStrToNull property that allows inserting NULL value insteadof empty string is added

28-Apr-11 New Features in SQL Server Data Access
Components 5.10:
Lazarus 0.9.30 and FPC 2.4.2 is supported
Support for Table-Valued Parameters is added
TMSTableData component for storing data of Table-Valued Parameter type is added
Support for SQL Server Compact Edition 4.0 is added
Support of API interface for managing FILESTREAM data is added

13-Sep-10 New Features in SQL Server Data Access
Components 5.00:
Embarcadero RAD Studio XE suppored

10-Sep-09 New Features in SQL Server Data Access
Components 4.80:
Embarcadero RAD Studio 2010 supported

23-Oct-08 New Features in SQL Server Data Access
Components 4.70:
Delphi 2009 and C++Builder 2009 supported
Extended Unicode support for Delphi 2007 added (special Unicode build)
Free Pascal 2.2 supported
Powerful design-time editors implemented in Lazarus
Completed with more comprehensive structured Help

23-May-08 New Features in SQL Server Data Access
Components 4.50:
Added compatibility with UniDAC© 2019 Devart

6

SQL Server Data Access Components

Improved support of default field values
Added ability to specify key fields for a dataset
Added support of automatic records locking
Added an option for setting lock wait timeout

09-Jan-08 New Features in SQL Server Data Access
Components 4.35:
SQL Server Compact Edition 3.5 supported
Tested with SQL Server 2008 CTP 4

27-Sep-07 New Features in SQL Server Data Access
Components 4.30:
CodeGear RAD Studio 2007 supported
Added enhanced support for User-defined Types of SQL Server
Added support for distributed transactions with the new TMSTransaction component
Added support for Query Notifications with the new TMSChangeNotification component
Improved support with SQL Server Compact Edition with the new TMSCompactConnection
component
Added support for getting results from queries with the FOR XML clause in readable view
Added ability to lock records and tables
TMSMetaData is enhanced with more schema row sets
Added support for connection encryption without certificate validation
Added ability to force record fetch for datasets open in FetchAll=False mode
Added support for detailed error messages output to DBMonitor
Added ability to use the default login database if no database is assigned on connect
Added the OnProgress event in TMSLoader

12-Jun-07 New Features in SQL Server Data Access
Components 4.10:
C++Builder 2007 supported

22-Mar-07 New Features in SQL Server Data Access
Components 4.00:
New functionality:
Delphi 2007 for Win32 supported© 2019 Devart

What's New

7

Implemented Disconnected Model for working offline and automatically connecting anddisconnecting
Implemented Local Failover for detecting connection loss and implicitly re-executing some
operations
Added DataSet Manager to control project datasets
New TMSScript component for easy execution of multistatement scripts with the following
features added:
Support for executing individual statements in scripts
Support for executing huge scripts stored in files with dynamic loading
Support for using standard SQL Server client tool syntax
New TMSServiceBroker component for SQL Server 2005 queuing and reliable messaging
added
New TCRBatchMove component for transferring data between all types of TDataSet
descendants added
New TMSDump component for loading data to and from the server added
Support for data export and
M:Devart.Dac.TVirtualTable.LoadFromFile(System.String,System.Boolean) to/from XML
WideMemo field type in Delphi 2006 supported
Support for sending messages to DBMonitor from any point in your program added
Added asynchronous execute and fetch modes
Compressed BLOB support

Support for more SQL Server functionality:
SQL Server Compact Edition supported
Multiple Active Result Sets (MARS) supported
Support for new data types, including XML, varchar(MAX), nvarchar(MAX), varbinary(MAX)added
Improved record insertion performance with new TMSLoader component
Added support for a new level of transaction isolation added
Support for more server objects in TMSMetaData added
Stored procedure parameters with default values supported

Extensions and improvements to existing functionality:
General performance improved
Master/detail functionality extensions:
Local master/detail relationships support added© 2019 Devart

8

SQL Server Data Access Components

Master/detail relationships in CachedUpdates mode support added
Working with calculated and lookup fields improvements:
Local sorting and filtering added
Record location speed increased
Improved working with lookup fields
Greatly increased performance of applying updates in CachedUpdates mode
Connection pool functionality improvements:
Efficiency significantly improved
API for draining the connection pool added
Ability to customize update commands by attaching external components to
TMSUpdateSQL objects added
Support for DefaultValues on record insertion added
Some performance improvements achieved:
NUMERIC fields fetching
Improved performance of executing Update commands while editing a dataset
DataSet refreshing
Record refreshing after updates and inserts
Support for selecting database name in TMSConnectDialog component

Usability improvements:
Syntax highlighting in design-time editors added
Completely restructured and clearer demo projects
Added FAQ section

28-Aug-06 New Features in SQL Server Data Access
Components 3.80:
Professional editions of Turbo Delphi, Turbo Delphi for .NET, Turbo C++ supported

26-Jan-06 New Features in SQL Server Data Access
Components 3.70:
Support for Delphi 2006 added
Support for SQL Server 2005 added

30-May-05 New Features in SQL Server Data Access
Components 3.55:
Ability of automatic preparing query with TCustomDADataSet.Options.AutoPrepare property© 2019 Devart

What's New

9

added
Ability to synchronize position at different DataSets with TCustomDADataSet.GotoCurrent
method added
Optimized MSSQLMonitor BLOB parameters processing
Improved behavior on editing master key on Master/Detail relation

24-Jan-05 New Features in SQL Server Data Access
Components 3.50:
Support for Delphi 2005 added
Support for SQL Server 2005 beta 2 added
Guid fields support for VirtualTable added

21-Oct-04 New Features in SQL Server Data Access
Components 3.00:
Support for Delphi 8 added
Local sorting ability with TMemDataSet.IndexFieldNames added
Connection pooling support
TCRDBGrid sources in Standard edition
MSDataAdapter component added.NET Windows Forms demo project added
ASP.NET demo project added
TMSConnection.GetStoredProcNames, GetTableNames, GetDatabaseNames added
TMSConnection.ClientVersion, ServerVersion added
Milliseconds support added

27-Jul-04 New Features in SQL Server Data Access
Components 2.45.2:
Methods TMSSQL.BreakExec and TCustomMSDataSet.BreakExec added
Property TMSConnection.Options.AutoTranslate added
Method ExecSQL in TMSConnection added
Methods GetTableNames and GetDatabaseNames in TMSConnection added
Unicode support for Locate on Win9x added

02-Oct-03 New Features in SQL Server Data Access
Components 2.45:© 2019 Devart

10

SQL Server Data Access Components

Property MSConnection.Options.WorkstationID added
Performance to insert large BLOBs improved
Performance significantly improved
Event TMSConnection.OnInfoMessage added
Multiple Errors support added
Property MSConnection.Options.ApplicationName added
Property TBlob.AsWideString added
Parameters parsing improved. Symbol ':' in string literals is ignored
Network error processing improved
Performance demo added

04-Apr-03 New Features in SQL Server Data Access
Components 2.40:
WideString support added
Property MSDataSet.Options.QuoteNames added
Property MSConnection.Options.KeepDesignConnected added
Property MSConnectDialog.StoreLogInfo published24-Feb-03 New Features in SQL Server Data Access
Components 2.35:
Speed optimization for opening small queries
MSConnection.Options added
Limited MSConnection.ConnectString support added
Output string and (var)bytes parameters are now obtained from the server with the
maximum length not depending on set Param.Size
DBMonitor client implementation moved to COM server

26-Dec-02 New Features in SQL Server Data Access
Components 2.30:
Delphi 7 supported
New memory management model for ftString and ftVarBytes types added
Support for blob fields in CachedUpdates mode added

09-Aug-02 New Features in SQL Server Data Access
Components 2.05:© 2019 Devart

What's New

11

DBMonitor support

18-Jul-02 New Features in SQL Server Data Access
Components 2.00:
Server cursors supported
Queries with Multiple Result Sets supported
Performance improved
Opening queries without fetching all rows to client (FetchAll = False) supported
UniDirectional support added
Quick getting Identity value
Refresh supported for StoredProc
FullRefresh supported
Check for old row values while executing Update and Delete added
Changed behavior on close connection with open transaction from Commit to Rollback

21-Mar-02 New Features in SQL Server Data Access
Components 1.30:
C++Builder 6 supported

08-Nov-01 New Features in SQL Server Data Access
Components 1.20:
Added TMSParam class to represent parameters
Query Analyzer and Enterprise Manager integration added
Accelerated getting identity value on refresh© 1997-2019
Devart. All Rights
Reserved.

2

Request Support

DAC Forum

Provide Feedback

General Information
This section contains general information about SQL Server Data Access Components
Overview
Features
Requirements
Compatibility
Using Several DAC Products in One IDE© 2019 Devart

12

SQL Server Data Access Components

Component List
Hierarchy Chart
Editions
Licensing and Subscriptions
Getting Support© 1997-2019
Devart. All Rights
Reserved.

2.1

Request Support

DAC Forum

Provide Feedback

Overview
SQL Server Data Access Components (SDAC) is a library of components that provides
access to Microsoft SQL Server databases. SDAC connects to SQL Server directly throughOLE DB. The SDAC library is designed to help programmers develop faster and cleaner SQL
Server database applications. SDAC is a complete replacement for standard SQL Serverconnectivity solutions and presents an efficient alternative to the Borland Database Engine foraccess to SQL Server.
The SDAC library is actively developed and supported by the Devart Team. If you havequestions about SDAC, email the developers at sdac@devart.com or visit SDAC online athttps://www.devart.com/sdac/.

Advantages of SDAC Technology
SDAC is a direct database connectivity wrapper built specifically for the SQL Server. SDAC
offers wide coverage of the SQL Server feature set, and emphasizes optimized data accessstrategies.

Wide Coverage of SQL Server Features
By providing access to the most advanced database functionality, SDAC allows developers toharness the full capabilities of the SQL Server and optimize their database applications.
SDAC provides complete support for working with SQL Server Compact Edition, SQL Server
queuing and reliable messaging, IRowsetFastLoad interface, working with metadata
information, MARS. Get a full list of supported SQL Server features in the Features topic.

Optimized CodeThe goal of SDAC is to enable developers to write efficient and flexible database applications.
The SDAC library is implemented using optimized code and advanced data accessalgorithms. Component interfaces undergo comprehensive performance tests and aredesigned to help you write efficient product data access layers. Find out more about using
SDAC to optimize your database applications in Increasing Performance.
© 2019 Devart

General Information

13

Compatibility with other Connectivity Methods
The SDAC interface retains compatibility with standard VCL data access components like
BDE. Existing BDE-based applications can be easily migrated to SDAC and enhanced to takeadvantage of SQL Server-specific features. Project migration can be automated with the
BDE/ADO Migration Wizard. Find out more about Migration Wizard in Using Migration Wizard.

Development and Support
SDAC is an SQL Server connectivity solution that is actively developed and supported. SDAC
comes with full documentation, demo projects, and fast (usually within one business day)technical support by the SDAC development team. Find out more about getting help or
submitting feedback and suggestions to the SDAC Development Team in the Getting Support
topic.
A description of the SDAC components is provided in the Component List.

Key Features
Direct access to server data. Does not require installation of other data provider layers(such as BDE and ODBC)VCL, LCL and FMX versions of library available
Full support of the latest Microsoft SQL Server versions, including Express and Compact
editions
Support for all SQL Server data types
Disconnected Model with automatic connection control for working with data offline
Local Failover for detecting connection loss and implicitly reexecuting certain operations
All types of local sorting and filtering, including by calculated and lookup fields
Automatic data updating with TMSQuery, TMSTable, and TMSStoredProc components
Unicode support
Support for many SQL Server-specific features, such as messaging and bulk copy
operations
Advanced script execution with TMSScript component
Support for using macros in SQL
Easy migration from BDE and ADO with Migration Wizard
Lets you use Professional Edition of Delphi and C++Builder to develop client/server
applications
Included annual SDAC Subscription with Priority Support
Licensed royalty-free per developer, per team, or per site

© 2019 Devart

14

SQL Server Data Access Components

The full list of SDAC features are available in the Features topic.

How does SDAC work?
SDAC uses OLE DB directly through a set of COM-based interfaces to connect to server.
SDAC is designed to be lightweight and consists of a minimal layer between your code and
SQL Server databases.
In comparison, the Borland Database Engine (BDE) uses several layers to access SQL
Server, and requires additional data access software to be installed on client machines.
The BDE data transfer protocol is shown below.

BDE Connection Protocol
SDAC works directly through OLE DB, which is a native SQL Server interface. Applications
with SDAC components access server directly:

SDAC Connection Flow
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 Devart

General Information

2.2

15

FeaturesIn this topic you will find the complete SDAC feature list sorted by categories.

General usability:
Direct access to server data. Does not require installation of other data provider layers(such as BDE and ODBC)Interface compatible with standard data access methods, such as BDE and ADO
VCL, LCL, and FMX versions of library available
Separated run-time and GUI specific parts allow you to create pure console applications
such as CGI
Unicode support

Network and connectivity:
Disconnected Model with automatic connection control for working with data offline
Local Failover for detecting connection loss and implicitly reexecuting certain operations
P:Devart.Sdac.TCustomMSConnection.ConnectString support
Ability to search for installed SQL Server databases in a local network
Support for connection encryption without certificate validation

Compatibility:
Full support of the latest Microsoft SQL Server versions, including Express and Compact
editions
Support for all SQL Server data types
Compatible with all IDE versions starting with Delphi 6, C++Builder 6 and Lazarus (Free
Pascal)Includes provider for UniDAC Standard Edition
Wide reporting component support, including support for InfoPower, ReportBuilder, andFastReport
Wide support of all standard Borland and third-party visual data-aware controls
Allows you to use Professional Edition of Delphi and C++Builder to develop client/server
applications

SQL Server technology support:
TMSLoader component for improving record insertion performance
TMSServiceBroker component for SQL Server queuing and reliable messaging
Enhanced support for User-defined Types of SQL Server© 2019 Devart

16

SQL Server Data Access Components

Enhanced support for SQL Server Compact Edition with the TMSCompactConnection
component
Possibility to change application name for a connection
Possibility to change workstation identifier for a connection
Configuration of OEM/ANSI character translation
Ability to lock records and tables

Performance:
High overall performance
Fast controlled fetch of large data blocks
Optimized string data storing
Advanced connection pooling
Incredible performance of applying updates in CachedUpdates mode
Caching of calculated and lookup fields
Fast Locate in a sorted DataSet
Preparing of user-defined update statements

Local data storage operations:
Database-independent data storage with TVirtualTable component
CachedUpdates operation mode
Local sorting and filtering, including by calculated and lookup fields
TMSMetaData Local master/detail relationship
Master/detail relationship in CachedUpdates mode

Data access and data management automation:
Automatic data updating with TMSQuery , TMSTable and TMSStoredProc components
Support for Query Notifications with the TMSChangeNotification component
Automatic record refreshing
Automatic query preparing
Support for getting results from queries with the FOR XML clause in readable viewSupport for ftWideMemo field type in Delphi 2006 and higher

Extended data access functionality:
Separate component for executing SQL statements
Simplified access to table data with TMSTable component
Ability to retrieve metadata information with TMSMetaData component© 2019 Devart

General Information

17

BLOB compression support
Support for using macros in SQL
FmtBCD fields support
NonBlocking mode allows background executing and fetching data in separate threads
Ability to customize update commands by attaching external components to
TMSUpdateSQL objects.
Deferred detail DataSet refresh in master/detail relationships
MIDAS technology support
Distributed transactions are supported with the TMSTransaction component

Data exchange:
Transferring data between all types of TDataSet descendants with TCRBatchMove
component
Data export and import to/from XML (ADO format)
Ability to synchronize positions in different DataSets

Script execution:
Advanced script execution features with TMSScript component
Support for executing individual statements in scripts
Support for executing huge scripts stored in files with dynamic loading
Optimized multi-statement script execution

SQL execution monitoring:
Extended SQL tracing capabilities provided by TMSSQLMonitor component and DBMonitor
Borland SQL Monitor support
Ability to send messages to DBMonitor from any point in your program

Visual extensions:
Includes source code of enhanced TCRDBGrid data-aware grid control
Customizable connection dialog
Cursor changes during non-blocking execution

Design-time enhancements:
DataSet Manager tool to control DataSet instances in the project
Advanced design-time component and property editors
Automatic design-time component linking© 2019 Devart

18

SQL Server Data Access Components

Easy migration from BDE and ADO with Migration Wizard
More convenient data source setup with the TMSDataSource component
Syntax highlighting in design-time editors

Product clarity:
Complete documentation sets
Printable documentation in PDF format
A large amount of helpful demo projects

Error handling:
Multiple error processing support
Unicode error messages support

Licensing and support:
Included annual SDAC Subscription with Priority Support
Licensed royalty-free per developer, per team, or per site

© 1997-2019
Devart. All Rights
Reserved.

2.3

Request Support

DAC Forum

Provide Feedback

Requirements
SDAC requires OLE DB installed on the workstation.
Note: In current versions of Microsoft Windows, as Windows 2000, OLE DB is alreadyincluded as standard package. But it's highly recommended to download latest version(newer than 2.5) of Microsoft Data Access Components (MDAC).
If you are working with SQL Server Compact Edition, you should have it installed. You candownload SQL Server Compact Edition from http://www.microsoft.com/sql/editions/compact/
default.mspx. For more information visit Working with SQL Server Compact Edition.

© 1997-2019
Devart. All Rights
Reserved.

2.4

Request Support

DAC Forum

Provide Feedback

Compatibility
SQL Server Compatibility
SDAC supports the following versions of SQL Server:© 2019 Devart

General Information

SQL Server 2017 (including Express edition)
SQL Server 2016 (including Express edition)
SQL Server 2014 (including Express edition)
SQL Server 2012 (including Express edition)
SQL Server 2008 R2 (including Express edition)
SQL Server 2008 (including Express edition)
SQL Server 2005 (including Express edition)
SQL Server 2000 (including MSDE)SQL Server 7
SQL Server Compact 4.0, 3.5, 3.1
SQL Azure

IDE Compatibility
SDAC is compatible with the following IDEs:
Embarcadero RAD Studio 10.3 Rio (Requires Release 2)
o Embarcadero Delphi 10.3 Rio for Windows 32-bit & 64-bit
o Embarcadero Delphi 10.3 Rio for macOS 32-bit & 64-bit
o Embarcadero Delphi 10.3 Rio for Linux 64-bit
o Embarcadero Delphi 10.3 Rio for iOS 32-bit & 64-bit
o Embarcadero Delphi 10.3 Rio for Android 32-bit & 64-bit
o Embarcadero C++Builder 10.3 Rio for Windows 32-bit & 64-bit
o Embarcadero C++Builder 10.3 Rio for macOSo Embarcadero C++Builder 10.3 Rio for iOS 32-bit & 64-bit
o Embarcadero C++Builder 10.3 Rio for Android
Embarcadero RAD Studio 10.2 Tokyoo Embarcadero Delphi 10.2 Tokyo for Windows 32-bit & 64-bit
o Embarcadero Delphi 10.2 Tokyo for macOSo Embarcadero Delphi 10.2 Tokyo for Linux 64-bit
o Embarcadero Delphi 10.2 Tokyo for iOS 32-bit & 64-bit
o Embarcadero Delphi 10.2 Tokyo for Android
o Embarcadero C++Builder 10.2 Tokyo for Windows 32-bit & 64-bit
o Embarcadero C++Builder 10.2 Tokyo for macOSo Embarcadero C++Builder 10.2 Tokyo for iOS 32-bit & 64-bit
o Embarcadero C++Builder 10.2 Tokyo for Android
Embarcadero RAD Studio 10.1 Berlino Embarcadero Delphi 10.1 Berlin for Windows 32-bit & 64-bit© 2019 Devart

19

20

SQL Server Data Access Components

o Embarcadero Delphi 10.1 Berlin for macOSo Embarcadero Delphi 10.1 Berlin for iOS 32-bit & 64-bit
o Embarcadero Delphi 10.1 Berlin for Android
o Embarcadero C++Builder 10.1 Berlin for Windows 32-bit & 64-bit
o Embarcadero C++Builder 10.1 Berlin for macOSo Embarcadero C++Builder 10.1 Berlin for iOS 32-bit & 64-bit
o Embarcadero C++Builder 10.1 Berlin for Android
Embarcadero RAD Studio 10 Seattleo Embarcadero Delphi 10 Seattle for Windows 32-bit & 64-bit
o Embarcadero Delphi 10 Seattle for macOSo Embarcadero Delphi 10 Seattle for iOS 32-bit & 64-bit
o Embarcadero Delphi 10 Seattle for Android
o Embarcadero C++Builder 10 Seattle for Windows 32-bit & 64-bit
o Embarcadero C++Builder 10 Seattle for macOSo Embarcadero C++Builder 10 Seattle for iOS 32-bit & 64-bit
o Embarcadero C++Builder 10 Seattle for Android
Embarcadero RAD Studio XE8
o Embarcadero Delphi XE8 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE8 for macOSo Embarcadero Delphi XE8 for iOS 32-bit & 64-bit
o Embarcadero Delphi XE8 for Android
o Embarcadero C++Builder XE8 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE8 for macOSo Embarcadero C++Builder XE8 for iOS 32-bit & 64-bit
o Embarcadero C++Builder XE8 for Android
Embarcadero RAD Studio XE7
o Embarcadero Delphi XE7 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE7 for macOSo Embarcadero Delphi XE7 for iOS
o Embarcadero Delphi XE7 for Android
o Embarcadero C++Builder XE7 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE7 for macOSo Embarcadero C++Builder XE7 for iOS
o Embarcadero C++Builder XE7 for Android
Embarcadero RAD Studio XE6
o Embarcadero Delphi XE6 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE6 for macOS© 2019 Devart

General Informationo Embarcadero Delphi XE6 for iOS
o Embarcadero Delphi XE6 for Android
o Embarcadero C++Builder XE6 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE6 for macOSo Embarcadero C++Builder XE6 for iOS
o Embarcadero C++Builder XE6 for Android
Embarcadero RAD Studio XE5 (Requires Update 2)o Embarcadero Delphi XE5 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE5 for macOSo Embarcadero Delphi XE5 for iOS
o Embarcadero Delphi XE5 for Android
o Embarcadero C++Builder XE5 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE5 for macOSo Embarcadero C++Builder XE5 for iOS
Embarcadero RAD Studio XE4
o Embarcadero Delphi XE4 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE4 for macOSo Embarcadero Delphi XE4 for iOS
o Embarcadero C++Builder XE4 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE4 for macOS
Embarcadero RAD Studio XE3 (Requires Update 2)o Embarcadero Delphi XE3 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE3 for macOSo Embarcadero C++Builder XE3 for Windows 32-bit & 64-bit
o Embarcadero C++Builder XE3 for macOS
Embarcadero RAD Studio XE2 (Requires Update 4 Hotfix 1)o Embarcadero Delphi XE2 for Windows 32-bit & 64-bit
o Embarcadero Delphi XE2 for macOSo Embarcadero C++Builder XE2 for Windows 32-bit
o Embarcadero C++Builder XE2 for macOS
Embarcadero RAD Studio XE
o Embarcadero Delphi XEo Embarcadero C++Builder XE
Embarcadero RAD Studio 2010
o Embarcadero Delphi 2010
o Embarcadero C++Builder 2010

© 2019 Devart

21

22

SQL Server Data Access Components

CodeGear RAD Studio 2009 (Requires Update 3)o CodeGear Delphi 2009o CodeGear C++Builder 2009
CodeGear RAD Studio 2007
o CodeGear Delphi 2007
o CodeGear C++Builder 2007
CodeGear RAD Studio 2006
o CodeGear Delphi 2006
o CodeGear C++Builder 2006
Borland Delphi 7
Borland Delphi 6 (Requires Update Pack 2 – Delphi 6 Build 6.240)
Borland C++Builder 6 (Requires Update Pack 4 – C++Builder 6 Build 10.166)
Lazarus 2.0.6 and Free Pascal 3.0.4 for Windows, Linux, macOS, FreeBSD for 32-bit and64-bit platforms
All the existing Delphi and C++Builder editions are supported: Architect, Enterprise,
Professional, Community, and Starter.
Lazarus and Free Pascal are supported only in Trial Edition and Professional Edition withsource code.

Supported Target Platforms
Windows, 32-bit and 64-bit
macOS, 32-bit and 64-bit
Linux, 32-bit (only in Lazarus and Free Pascal) and 64-bit
iOS, 32-bit and 64-bit
Android, 32-bit and 64-bit
FreeBSD (only in Lazarus and Free Pascal) 32-bit and 64-bit
Note that support for 64-bit Windows and macOS was introduced in RAD Studio XE2, and is
not available in older versions of RAD Studio. Support for iOS is available since RAD Studio
XE4, but support for iOS 64-bit is available since RAD Studio XE8. Support for Android isavailable since RAD Studio XE5. Support for Linux 64-bit is available since RAD Studio 10.2
Tokyo. Support for macOS 64-bit is available since RAD Studio 10.3 Rio. Support for Android
64-bit is available since RAD Studio 10.3.3 Rio.

© 2019 Devart

General Information

23

Devart Data Access Components Compatibility
All DAC products are compatible with each other.
But, to install several DAC products to the same IDE, it is necessary to make sure that all
DAC products have the same common engine (BPL files) version. The latest versions of
DAC products or versions with the same release date always have the same version of thecommon engine and can be installed to the same IDE.

© 1997-2019
Devart. All Rights
Reserved.

2.5

Request Support

DAC Forum

Provide Feedback

Using Several DAC Products in One IDE
UniDAC, ODAC, SDAC, MyDAC, IBDAC, PgDAC, LiteDAC and VirtualDAC components use
common base packages listed below:
Packages:
dacXX.bpl
dacvclXX.bpl
dcldacXX.bpl
Note that product compatibility is provided for the current build only. In other words, if you
upgrade one of the installed products, it may conflict with older builds of other products. In
order to continue using the products simultaneously, you should upgrade all of them at thesame time.

© 1997-2019
Devart. All Rights
Reserved.

2.6

Request Support

DAC Forum

Provide Feedback

Component List
This topic presents a brief description of the components included in the SQL Server Data
Access Components library. Click on the name of each component for more information.
These components are added to the SDAC page of the Component palette except for
TCRBatchMove and TVirtualTable components. TCRBatchMove and TVirtualTable
components are added to the Data Access page of the Component palette. Basic SDAC
components are included in all SDAC editions. SDAC Professional Edition components are
not included in SDAC Standard Edition.

Basic SDAC components© 2019 Devart

24

SQL Server Data Access Components

TMSConnection Lets you set up and control connections to SQL Server.

TMSQueryUses SQL statements to retrieve data from SQL Server table ortables and supply it to one or more data-aware components
through a TDataSource component. Provides flexible update ofdata.

TMSTableLets you retrieve and update data in a single table without writing
SQL statements.

TMSStoredProc Executes stored procedures and functions.
TMSSQL

Executes SQL statements and stored procedures that do not
return rowsets.

TMSScript

Executes sequences of SQL statements.

TMSUpdateSQL Lets you tune update operations for DataSet component.
TMSDataSource

Provides an interface between a SDAC dataset components
and data-aware controls on a form.

TMSSQLMonitor

Interface for monitoring dynamic SQL execution in SDAC-based
applications.

TMSConnectDial Is used on client side to supply username, password, databaseogand server name.
TMSTableData

Is used for working with user-defined table types in SQL Server
2008.

TVirtualTable

Dataset that stores data in memory. This component is placedon the Data Access page of the Component palette.

TVirtualDataSet Dataset that processes arbitrary non-tabular data.

SDAC Professional Edition components
TMSEncryptor

Represents data encryption and decryption in client application.

TMSLoader

Provides quick data loading to SQL Server database.

© 2019 Devart

General Information

25

Serves to store a database or its parts as a script and also torestore database from received script.

TMSDump

TMSServiceBrok Lets you send and receive messages using the SQL Server
erService Broker system.
TMSMetaData

Retrieves embracing metadata on specified SQL object.

TMSChangeNotif Lets you react on different server side changes on-the-fly. Basedicationon the Query Notifications mechanism of SQL Server.
TMSTransaction

Lets you control distributed transactions via Microsoft
Distributed Transaction Coordinator.

TMSCompactCo Lets you set up and control connections to SQL Server Compact
nnection
Edition.
Transfers data between all types of TDataSets descendants.
TCRBatchMove This component is placed on the Data Access page of theComponent palette.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.

2.7

Hierarchy Chart
Many SDAC classes are inherited from standard VCL/LCL classes. The inheritance hierarchy
chart for SDAC is shown below. The SDAC classes are represented by hyperlinks that point
to their description in this documentation. A description of the standard classes can be foundin the documentation of your IDE.
TObject|—TPersistent|—TComponent|—TCustomConnection||—TCustomDAConnection||—TCustomMSConnection||—TMSConnection||—TMSCompactConnection|—TDataSet||© 2019 Devart|—TMemDataSet|—TCustomDADataSet

26

SQL Server Data Access Components|||—TCustomMSDataSet|||—TMSQuery|||—TCustomMSTable

|

|

|

|

|

|—TCustomMSStoredProc

|

|

|

|

|

|—TMSMetaData||—TVirtualTable|—TMSTable|—TMSStoredProc||—TMSTableData|—TDataSource|||—TCRDataSource|—TMSDataSource|—TCustomDASQL||—TMSSQL|—TCustomDASQLMonitor||—TMSSQLMonitor|—TCustomConnectDialog||—TMSConnectDialog|—TDALoader||—TMSLoader|—TDADump||—TMSDump|—TDAScript||—TMSScript|—DADataAdapter||—MSDataAdapter|—TDATransaction||TMSTransaction|—TCRBatchMove|—TMSChangeNotification|—TMSServiceBroker|—TField||—TMSUDTField||—TMSXMLField|—TCREncryptor|—TMSEncryptor© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 Devart

General Information

27

Devart. All Rights
Reserved.

2.8

Editions
SQL Server Data Access Components comes in three editions: SDAC Standard Edition,
SDAC Professional Edition, and SDAC Trial Edition.
SDAC Standard Edition includes the SDAC basic connectivity components and the SDAC
Migration Wizard. SDAC Standard Edition is a good choice for beginning SQL Server
developers and a cost-effective solution for database application developers who only needbasic connectivity functionality for SQL Server.
SDAC Professional Edition shows off the full power of SDAC, enhancing SDAC Standard
Edition with support for SQL Server-specific functionality. SDAC Professional Edition isintended for serious application developers who want to take advantage of all the SQL Serverspecific functionality support provided by SDAC.
SDAC Trial Edition is the evaluation version of SDAC. It includes all the functionality of SDAC
Professional Edition with a trial limitation of 60 days. C++Builder has additional trial
limitations*.
You can get source code of all the component classes in SDAC by purchasing the special
SDAC Professional Edition with Source Code**.

SDAC Edition Matrix
FeatureDirect connectivity
Connection without SQL Server client

Desktop Application Development
Windows
macOS
Linux

Mobile Application Development© 2019 DevartStandard

Professional

28

SQL Server Data Access Components

iOS
Android

Data Access Components
TMSConnection
TMSQuery
TMSSQL
TMSTable
TMSStoredProc
TMSUpdateSQLTMSDataSource
Script executing
TMSScript
Transactions managing
TMSTransaction
Fast data loading into the server
TMSLoader

SQL Server Specific Components
Working with user-defined table types in SQL Server
2008
TMSTableData
Connection to SQL Server Compact Edition
TMSCompactConnection
Reaction on server side changes on-the-fly
TMSChangeNotification
Sending messages with Service Broker system
TMSServiceBroker
Obtaining metainformation about database objects
TMSMetadata
Storing a database as a script
TMSDump

DataBase Activity Monitoring
Monitoring of per-component SQL execution
TMSSQLMonitor© 2019 Devart

General Information

29

Additional components
Advanced connection dialog
TMSConnectDialog
Data encryption and decryption
TMSEncryptor
Data storing in memory table
TVirtualTable
Advanced DBGrid with extended functionality
TCRDBGrid
Records transferring between datasets
TCRBatchMove

Design-Time Features
Enhanced component and property editors
Migration Wizard
DataSet Manager

Cross IDE Support
Lazarus and Free Pascal Support ** Available only in editions with source code.

© 1997-2019
Devart. All Rights
Reserved.

2.9

Request Support

DAC Forum

Provide Feedback

Licensing
PLEASE READ THIS LICENSE AGREEMENT CAREFULLY. BY INSTALLING OR USING
THIS SOFTWARE, YOU INDICATE ACCEPTANCE OF AND AGREE TO BECOME BOUND
BY THE TERMS AND CONDITIONS OF THIS LICENSE. IF YOU DO NOT AGREE TO THETERMS OF THIS LICENSE, DO NOT INSTALL OR USE THIS SOFTWARE AND
PROMPTLY RETURN IT TO DEVART.

© 2019 Devart

30

SQL Server Data Access Components

INTRODUCTION
This Devart end-user license agreement ("Agreement") is a legal agreement between you(either an individual person or a single legal entity) and Devart, for the use of SDAC software
application, source code, demos, intermediate files, printed materials, and online or electronic
documentation contained in this installation file. For the purpose of this Agreement, thesoftware program(s) and supporting documentation will be referred to as the "Software".

LICENSE
1. GRANT OF LICENSE
The enclosed Software is licensed, not sold. You have the following rights and privileges,
subject to all limitations, restrictions, and policies specified in this Agreement.
1.1. If you are a legally licensed user, depending on the license type specified in theregistration letter you have received from Devart upon purchase of the Software, you areentitled to either:
install and use the Software on one or more computers, provided it is used by 1 (one) for
the sole purposes of developing, testing, and deploying applications in accordance with thisAgreement (the "Single Developer License"); or
install and use the Software on one or more computers, provided it is used by up to 4 (four)developers within a single company at one physical address for the sole purposes ofdeveloping, testing, and deploying applications in accordance with this Agreement (the"Team Developer License"); or
install and use the Software on one or more computers, provided it is used by developers ina single company at one physical address for the sole purposes of developing, testing, anddeploying applications in accordance with this Agreement (the "Site License").
1.2. If you are a legally licensed user of the Software, you are also entitled to:
make one copy of the Software for archival purposes only, or copy the Software onto thehard disk of your computer and retain the original for archival purposes;
develop and test applications with the Software, subject to the Limitations below;
create libraries, components, and frameworks derived from the Software for personal use
only;
deploy and register run-time libraries and packages of the Software, subject to theRedistribution policy defined below.
1.3. You are allowed to use evaluation versions of the Software as specified in the Evaluation
section.

© 2019 Devart

General Information

31

No other rights or privileges are granted in this Agreement.

2. LIMITATIONS
Only legally registered users are licensed to use the Software, subject to all of the conditionsof this Agreement. Usage of the Software is subject to the following restrictions.
2.1. You may not reverse engineer, decompile, or disassemble the Software.
2.2. You may not build any other components through inheritance for public distribution orcommercial sale.
2.3. You may not use any part of the source code of the Software (original or modified) tobuild any other components for public distribution or commercial sale.
2.4. You may not reproduce or distribute any Software documentation without express written
permission from Devart.
2.5. You may not distribute and sell any portion of the Software without integrating it into your
Applications as Executable Code, except Trial edition that can be distributed for free as
original Devart's SDAC Trial package.
2.6. You may not transfer, assign, or modify the Software in whole or in part. In particular, theSoftware license is non-transferable, and you may not transfer the Software installation
package.
2.7. You may not remove or alter any Devart's copyright, trademark, or other proprietary rights
notice contained in any portion of Devart units, source code, or other files that bear such a
notice.

3. REDISTRIBUTION
The license grants you a non-exclusive right to compile, reproduce, and distribute any new
software programs created using SDAC. You can distribute SDAC only in compiled
Executable Programs or Dynamic-Link Libraries with required run-time libraries andpackages.
All Devart's units, source code, and other files remain Devart's exclusive property.

4. TRANSFER
You may not transfer the Software to any individual or entity without express written
permission from Devart. In particular, you may not share copies of the Software under “Single
Developer License” and “Team License” with other co-developers without obtaining proper
license of these copies for each individual.

5. TERMINATION
Devart may immediately terminate this Agreement without notice or judicial resolution in theevent of any failure to comply with any provision of this Agreement. Upon such termination© 2019 Devart

32

SQL Server Data Access Components

you must destroy the Software, all accompanying written materials, and all copies.

6. EVALUATION
Devart may provide evaluation ("Trial") versions of the Software. You may transfer or
distribute Trial versions of the Software as an original installation package only. If the Software
you have obtained is marked as a "Trial" version, you may install and use the Software for aperiod of up to 60 calendar days from the date of installation (the "Trial Period"), subject to theadditional restriction that it is used solely for evaluation of the Software and not in conjunction
with the development or deployment of any application in production. You may not use
applications developed using Trial versions of the Software for any commercial purposes.
Upon expiration of the Trial Period, the Software must be uninstalled, all its copies and allaccompanying written materials must be destroyed.

7. WARRANTYThe Software and documentation are provided "AS IS" without warranty of any kind. Devart
makes no warranties, expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose or use.

8. SUBSCRIPTION AND SUPPORTThe Software is sold on a subscription basis. The Software subscription entitles you to
download improvements and enhancement from Devart’s web site as they become available,
during the active subscription period. The initial subscription period is one year from the dateof purchase of the license. The subscription is automatically activated upon purchase, andmay be subsequently renewed by Devart, subject to receipt applicable fees. Licensed usersof the Software with an active subscription may request technical assistance with using theSoftware over email from the Software development. Devart shall use its reasonableendeavours to answer queries raised, but does not guarantee that your queries or problems
will be fixed or solved.
Devart reserves the right to cease offering and providing support for legacy IDE versions.

9. COPYRIGHTThe Software is confidential and proprietary copyrighted work of Devart and is protected byinternational copyright laws and treaty provisions. You may not remove the copyright noticefrom any copy of the Software or any copy of the written materials, accompanying theSoftware.
This Agreement contains the total agreement between the two parties and supersedes anyother agreements, written, oral, expressed, or implied.

© 2019 Devart

General Information© 1997-2019
Devart. All Rights
Reserved.

2.10

Request Support

DAC Forum

33

Provide Feedback

Getting Support
This page lists several ways you can find help with using SDAC and describes the SDAC
Priority Support program.

Support Options
There are a number of resources for finding help on installing and using SDAC.
You can find out more about SDAC installation or licensing by consulting the Licensing and
FAQ sections.
You can get community assistance and technical support on the SDAC Community Forum.
You can get advanced technical assistance by SDAC developers through the SDAC
Priority Support program.
If you have a question about ordering SDAC or any other Devart product, please contact
sales@devart.com.

SDAC Priority Support
SDAC Priority Support is an advanced product support service for getting expedited individual
assistance with SDAC-related questions from the SDAC developers themselves. Priority
Support is carried out over email and has two business days response policy. Priority Support
is available for users with an active SDAC Subscription.
To get help through the SDAC Priority Support program, please send an email tosupport@devart.com describing the problem you are having. Make sure to include thefollowing information in your message:
The version of Delphi or C++Builder you are using.
Your SDAC Registration number.
Full SDAC edition name and version number. You can find both of these from the SDAC |SDAC About menu in the IDE.
Versions of the SQL Server server and client you are using.
A detailed problem description.
If possible, a small test project that reproduces the problem. It is recommended to use
Northwind objects only. Please include definitions for all and avoid using third-party
components.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

34

SQL Server Data Access Components

Reserved.

2.11

Frequently Asked Questions
This page contains a list of Frequently Asked Questions for SQL Server Data Access
Components.
If you have encounter a question with using SDAC, please browse through this list first. If thispage does not answer your question, refer to the Getting Support topic in SDAC help.
Installation and Deployment
1. I am having a problem installing SDAC or compiling SDAC-based projects...
You may be having a compatibility issue that shows up in one or more of the following forms:o Get a "Setup has detected already installed DAC packages which are incompatible withcurrent version" message during SDAC installation.
o Get a "Procedure entry point ... not found in ... " message when starting IDE.
o Get a "Unit ... was compiled with a different version of ..." message on compilation.
You can have such problems if you installed incompatible SDAC, ODAC, MyDAC or IBDAC
versions. All these products use common base packages. The easiest way to avoid the
problem is to uninstall all installed DAC products and then download from our site and install
the last builds.
2. What software should be installed on the client computer so that my applications
that use SDAC can run?
SDAC requires OLE DB installed on the workstation. In current versions of Microsoft
Windows, such as Windows 2000, OLE DB is already included as part of the standard
installation. But it is highly recommended to download the latest version (newer than 2.5) of
Microsoft Data Access Components (MDAC).
Many features of SQL Server like Query Notifications, MARS require Microsoft SQL Server
Native Client. If you need to use these features, you should download and install Microsoft
SQL Server Native Client.
For applications that use SQL Server Compact Edition, the server itself is required to beinstalled on the client computer.
For more information, please refer to the Deployment topic of the SDAC help.
Licensing and Subscriptions
1. Am I entitled to distribute applications written with SDAC?

© 2019 Devart

General Information

35

If you have purchased a full version of SDAC, you are entitled to distribute pre-compiled
programs created with its use. You are not entitled to propagate any components inheritedfrom SDAC or using SDAC source code. For more information see the License.rtf file in yourSDAC installation directory.
2. Can I create components using SDAC?
You can create your own components that are inherited from SDAC or that use the SDAC
source code. You are entitled to sell and distribute compiled application executables that use
such components, but not their source code and not the components themselves.
3. What licensing changes can I expect with SDAC 4.00?
The basic SDAC license agreement will remain the same. With SDAC 4.00, the SDAC
Edition Matrix will be reorganized and a new SDAC Subscription Program will be introduced.
4. What do the SDAC 4.00 Edition Levels correspond to?
SDAC 4.00 will come in four editions: Trial, Standard, Professional, and Professional with
Sources.
When you upgrade to the new version, your edition level will be automatically updated using
the following Edition Correspondence Table.

Edition Correspondence Table for Upgrading to SDAC 4.00

Old Edition Level- No
Correspondence SDAC Standard
EditionSDAC Professional
EditionSDAC Trial Edition

New Edition Level
SDAC Standard
EditionSDAC Professional
EditionSDAC Professional
Edition with Sources
SDAC Trial Edition

The feature list for each edition can be found in the SDAC documentation and on the SDAC
website.
5. I have a registered version of SDAC. Will I need to pay to upgrade to futureversions?
After SDAC 4.00, all upgrades to future versions are free to users with an active SDAC
© 2019 Devart

36

SQL Server Data Access Components

Subscription.
Users that have a registration for versions of SDAC prior to SDAC 4.00 will have to firstupgrade to SDAC 4.00 to jump in on the Subscription program.

6. What are the benefits of the SDAC Subscription program?
The SDAC Subscription Program is an annual maintenance and support service for SDAC
users.
Users with a valid SDAC Subscription get the following benefits:o Access to new versions of SDAC when they are releasedo Access to all SDAC updates and bug fixes
o Product support through the SDAC Priority Support programo Notification of new product versions
Priority Support is an advanced product support program which offers you expedited
individual assistance with SDAC-related questions from the SDAC developers themselves.
Priority Support is carried out over email and has a two business day response policy.
The SDAC Subscription Program is available for registered users of SDAC 4.00 and higher.
7. Can I use my version of SDAC after my Subscription expires?
Yes, you can. SDAC version licenses are perpetual.
8. I want a SDAC Subscription! How can I get one?
An annual SDAC Subscription is included when ordering or upgrading to any registered (nonTrial) edition of SDAC 4.00 or higher.
You can renew your SDAC Subscription on the SDAC Ordering Page. For more information,please contact sales@devart.com.
9. Does this mean that if I upgrade to SDAC 4 from SDAC 3, I'll get an annual SDAC
Subscription for free?
Yes.
10.How do I upgrade to SDAC 4.00?
To upgrade to SDAC 4.00, you can get a Version Update from the SDAC Ordering Page. For
more information, please contact sales@devart.com.

© 2019 Devart

General Information

37

Performance
1. How productive is SDAC?
SDAC uses the lowest documented protocol level (OLE DB) to access the database server.
This allows SDAC to achieve high performance. From time to time we compare SDAC withother products, and SDAC always takes first place.
2. Why does the Locate function work so slowly the first time I use it?
Locate is performed on the client. So if you had set FetchAll to False when opening yourdataset, cached only some of the rows on the client, and then invoked Locate, SDAC will
have to fetch all the remaining rows from the server before performing the operation. On
subsequent calls, Locate should work much faster.
If the Locate method keeps working slowly on subsequent calls or you are working with
FetchAll=True, try the following. Perform local sorting by a field that is used in the Locate
method. Just assign corresponding field name to the IndexFieldNames property.
How To1. How can I enable syntax highlighting in SDAC component editors at design time?
To enable syntax highlighting for SDAC, you should download and install the freeware SynEdit
component set.
2. How can I determine which version of SDAC am I using?
You can determine your SDAC version number in several ways:o During installation of SDAC, consult the SDAC Installer screen.
o After installation, see the history.html file in your SDAC installation directiory.
o At design-time, select SQL Server | About SDAC from the main menu of your IDE.
o At run-time, check the value of the SdacVersion and DACVersion constants.
3. How can I stop the cursor from changing to an hour glass during query execution?
Just set the DBAccess.ChangeCursor variable to False anywhere in your program. The
cursor will stop changing after this command is executed.
4. How can I execute a query saved in the SQLInsert, SQLUpdate, SQLDelete, or
SQLRefresh properties of a SDAC dataset?
The values of these properties are templates for query statements, and they cannot be
manually executed. Usually there is no need to fill these properties because the text of thequery is generated automatically.

© 2019 Devart

38

SQL Server Data Access Components

In special cases, you can set these properties to perform more complicated processing
during a query. These properties are automatically processed by SDAC during the executionof the Post, Delete, or RefreshRecord methods, and are used to construct the query to theserver. Their values can contain parameters with names of fields in the underlying data
source, which will be later replaced by appropriate data values.
For example, you can use the SQLInsert template to insert a row into a query instance asfollows.
o Fill the SQLInsert property with the parametrized query template you want to use.
o Call Insert.
o Initialize field values of the row to insert.
o Call Post.
The value of the SQLInsert property will then be used by SDAC to perform the last step.
Setting these properties is optional and allows you to automatically execute additional SQL
statements, add calls to stored procedures and functions, check input parameters, and/or
store comments during query execution. If these properties are not set, the SDAC dataset
object will generate the query itself using the appropriate insert, update, delete, or refresh
record syntax.
5. How can I get a list of the databases on the server?
Use the TCustomDAConnection.GetDatabaseNames method.
6. How can I get a list of the tables list in a database?
Use the TCustomDAConnection.GetTableNames method.
7. Some questions about the visual part of SDAC
The following questions usually arise from the same problem:o I set the Debug property to True but nothing happens!
o While executing a query, the screen cursor does not change to an hour-glass.
o Even if I have LoginPromp set to True, the connect dialog does not appear.
To fix this problem, you should add the SdacVcl unit to the uses clause of your project.
General Questions
1. I would like to develop an application that works with SQL Server. Should I use
SDAC or DbxSda?
DbxSda is our dbExpress driver for SQL Server. dbExpress technology serves for providing a© 2019 Devart

General Information

39

more or less uniform way to access different servers (SQL Server, MySQL, Oracle and soon). It is based on drivers that include server-specific features. Like any universal tool, inmany specialized cases dbExpress providers lose some functionality. For example, thedbExpress design-time is quite poor and cannot be expanded.
SDAC is a specialized set of components for SQL Server, which has advanced serverspecific design-time and a component interface similar to that of BDE.
We tried to include maximal support of SQL Server-specific features in both DbxSda andSDAC. However, the nature of dbExpress technology has some insurmountable restrictions.
For example, Unicode fields cannot be passed from a driver to dbExpress.
SDAC and DbxSda use the same kernel and thus have similar performance. In some cases
dbExpress is slower because data undergoes additional conversion to correspond to
dbExpress standards.
To summarise, if it is important for you to be able to quickly adapt your application to a
database server other than SQL Server, it is probably better to use DbxSda. In other cases,
especially when migrating from BDE or ADO, you should use SDAC.
2. What are the advantages of SDAC over Delphi ADO components for accessing SQL
Server?
ADO is a universal components while SDAC is specialized in SQL Server, so SDAC takes
into account lots of server specific features. SDAC has great benefit in performance (5-10times in different tests) because it works directly through OLE DB, which is a native SQL
Server interface. Moreover, SDAC provides advanced design-time editors.
3. Behaviour of my application has changed when I upgraded SDAC. How can I restore
the old behaviour with the new version?
We always try to keep SDAC compatible with previous versions, but sometimes we have tochange behaviour of SDAC in order to enhance its functionality, or avoid bugs. If either ofchanges is undesirable for your application, and you want to save the old behaviour, pleaserefer to the "Compatibility with previous versions" topic in SDAC help. This topic describes
such changes, and how to revert to the old SDAC behaviour.
4. On connect, I get an "OLE DB error occured. Code 800401F0h. CoInitialize has notbeen called" error. What can I do?
As SDAC uses OLE DB, it is necessary to initialize OLE by calling CoInitialize before a newconnection is established. Usually VCL does this automatically. SDAC does not call to the
CoInitialize and CoUninitialize functions itself, as this may cause unexpected problems if
OLE is used in the program by someone else.
© 2019 Devart

40

SQL Server Data Access Components

5. Are the SDAC connection components thread-safe?
Yes, SDAC is thread-safe but there is a restriction. But the same TCustomMSConnection
object descendant cannot be used in several threads. So if you have a multithreaded
application, you should have a TCustomMSConnection object descendant for each threadthat uses SDAC.
6. When editing a DataSet, I get an exception with the message 'Update failed. Found%d records.' or 'Refresh failed. Found %d records.'
This error occurs when the database server is unable to determine which record to modify ordelete. In other words, there are either more than one record or no records that suit the
UPDATE criteria. Such situation can happen when you omit the unique field in a SELECT
statement (TCustomDADataSet.SQL) or when another user modifies the table
simultaneously. This exception can be suppressed. Refer to TCustomDADataSet.Options
topic in SDAC help for more information.

7. Some questions with using TCustomDADataSet.FetchAll=False mode
Common issues when using FetchAll=False:o I have problems working with temporary tables.
o I have problems working with transactions.
o Sometimes my application hangs on applying changes to database.
Usage of FetchAll=False mode has many advantages; however, it also has some restrictions
since it requires an additional connection to server to be created for data fetching. The
additional connection is created to prevent the main connection from blocking.
These problems can be avoided by setting the FetchAll property to True. Please see
description of the FetchAll propery and the CreateConnection option in SDAC help for more
information.
One more way to solve these problems is to use the Multiple Active Result Sets (MARS)
feature. This feature lets you keep more than one unfetched record set within a single
connection. To enable MARS, set the MultipleActiveResultSets option of TMSConnection toTrue. Note: To use MARS, you will need to have SQL Server and SQL Native Client installed.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartGetting Started

341

Getting Started
This section introduces SQL Server Data Access Components. It contains the information on
how to install SQL Server Data Access Components, quick walktroughs to get started
developing applications with it, information on technical licensing and deployment, and brief
description of SDAC documentation and samples.
Installation
Migration Wizard
Migration from BDE
Migration from ADO
Logging on to SQL Server
Logging on to SQL Server Compact
Creating Database Objects
Deleting Data From Tables
Inserting Data Into Tables
Retrieving Data
Modifying DataStored Procedures
Working With Result Sets Using Stored Procedures© 1997-2019
Devart. All Rights
Reserved.

3.1

Request Support

DAC Forum

Provide Feedback

Installation
This topic contains the environment changes made by the SDAC installer. If you are having
problems with using SDAC or compiling SDAC-based products, check this list to make sure
your system is properly configured.
Compiled versions of SDAC are installed automatically by the SDAC Installer for all supported
IDEs except for Lazarus. Versions of SDAC with Source Code must be installed manually.
Installation of SDAC from sources is described in the supplied ReadmeSrc.html file.

Before installing SDAC ...
Two versions of SDAC cannot be installed in parallel for the same IDE, and, since the Devart
Data Access Components products have some shared bpl files, newer versions of SDAC
may be incompatible with older versions of MyDAC, IBDAC, and ODAC.
So before installing a new version of SDAC, uninstall any previous version of SDAC you may
have, and check if your new install is compatible with other Devart Data Access Components© 2019 Devart

42

SQL Server Data Access Components

products you have installed. For more information please see Using several products in one
IDE. If you run into problems or have any compatibility questions, please email
sdac@devart.com
Note: You can avoid performing SDAC uninstallation manually when upgrading to a newversion by directing the SDAC installation program to overwrite previous versions. To do this,execute the installation program from the command line with a /force parameter (Start | Run
and type sdacXX.exe /force, specifying the full path to the appropriate version of theinstallation program).

Installed packages
Note: %SDAC% denotes the path to your SDAC installation directory.

Delphi/C++Builder Win32 project packages
Name
dacXX.bpl
dcldacXX.bpl
dacvclXX.bpl*
sdacXX.bpl
dclsdacXX.bpl
sdacvclXX.bpl*
crcontrolsXX.bpl

Description
Location
DAC run-time package Windows\System32
DAC design-time
Delphi\Binpackage
DAC VCL support
Delphi\Binpackage
SDAC run-time package Windows\System32
SDAC design-time
Delphi\Binpackage
VCL support package
Delphi\Bin
TCRDBGrid component Delphi\BinAdditional packages for using SDAC managers and wizards
Name
Description
datasetmanagerXX. DataSet Manager
bpl
package
SDAC BDE Migration
oramigwizardXX.dll
wizardLocation
Delphi\Bin%SDAC%\Bin

Environment Changes
To compile SDAC-based applications, your environment must be configured to have accessto the SDAC libraries. Environment changes are IDE-dependent.
For all instructions, replace %SDAC% with the path to your SDAC installation directory© 2019 DevartGetting Started

43

Delphi%SDAC%\Lib should be included in the Library Path accessible from Tools | Environment
options | Library.
The SDAC Installer performs Delphi environment changes automatically for compiled
versions of SDAC.

C++Builder
C++Builder 6:$(BCB)\SDAC\Lib should be included in the Library Path of the Default Project Options
accessible from Project | Options | Directories/Conditionals.
$(BCB)\SDAC\Include should be included in the Include Path of the Default Project Options
accessible from Project | Options | Directories/Conditionals.

C++Builder 2006, 2007:$(BCB)\SDAC\Lib should be included in the Library search path of the Default Project
Options accessible from Project | Default Options | C++Builder | Linker | Paths and Defines.
$(BCB)\SDAC\Include should be included in the Include search path of the Default Project
Options accessible from Project | Default Options | C++Builder | C++ Compiler | Paths andDefines.
The SDAC Installer performs C++Builder environment changes automatically for compiled
versions of SDAC.

LazarusThe SDAC installation program only copies SDAC files. You need to install SDAC packages
to Lazarus IDE manually. Open %SDAC%\Source\Lazarus1\dclsdac10.lpk (for Trial version%SDAC%\Packages\dclsdac10.lpk) file in Lazarus and press the Install button. After that
Lazarus IDE will be rebuilded with SDAC packages.
Do not press the Compile button for the package. Compiling will fail because there are no
SDAC sources.
To check that your environment has been properly configured, try to compile one of the demo
projects included with SDAC. The SDAC demo projects are located in %SDAC%/Demos.

Installation of Additional Components and Add-ins
DBMonitor
DBMonitor is an easy-to-use tool to provide visual monitoring of your database applications. It© 2019 Devart

44

SQL Server Data Access Components

is provided as an alternative to Borland SQL Monitor which is also supported by SDAC.
DBMonitor is intended to hamper application being monitored as little as possible. For more
information, visit the DBMonitor page online.

© 1997-2019
Devart. All Rights
Reserved.

3.2

Request Support

DAC Forum

Provide Feedback

Migration Wizard
NOTE:
Migration Wizard is available only for Delphi IDE and is not available for C++Builder.
Migration Wizard allows you to convert your BDE or ADO projects to SDAC. This wizard
replaces BDE or ADO components in the specified project (dfm-and pas-files) with SDAC
ones.
To convert a project, perform the following steps.
Select Migration Wizard from SQL Server menu
Select Replace BDE components or Replace ADO components to replacecorresponding components with SDAC and press the Next button.
Select the location of the files to search - current open project or disc folder.
If you have selected Disc folder on the previous step, specify the required folder and specify
whether to process subfolders. Press the Next button.
Select whether to make backup (it is highly recommended to make a backup), backup
location, and log parameters, and press the Next button. Default backup location isRBackup folder in your project folder.
Check your settings and press the Finish button to start the conversion operation.
The project should be saved before conversion. You will be asked before saving it. ClickYes to continue project conversion.
After the project conversion it will be reopened.
The Wizard just replaces all standard BDE/ADO components. Probably you will need tomake some changes manually to compile your application successfully.
If some problems occur while making changes, you can restore your project from backup file.
To do this perform the following steps.
Select Migration Wizard from SQL Server menu
Select Restore original files from backup and press the Next button.
Select the backup file. By default it is RExpert.reu file in RBackup folder of your converted
project. Press the Next button.
Check your settings and press the Finish button to start the conversion operation.
Press Yes in the dialog that appeared.
© 2019 DevartGetting Started

45

Your project will be restored to its previous state.

See Also
Migration from BDE
Migration from ADO© 1997-2019
Devart. All Rights
Reserved.

3.3

Request Support

DAC Forum

Provide Feedback

Migration from BDE
In SDAC the interests of BDE application developers were taken into consideration. So
starting to use SDAC after working with BDE would be easy even for developing complex
projects. Moreover, SDAC does not have problems like ones with LiveQuery and compatibilityof applications developed using different versions in BDE. On SDAC developing BDE users
interests were taken in consideration so conversion from using BDE into SDAC can bepassed without difficulties even for complex projects. Moreover, SDAC does not haveproblems appropriated BDE with LiveQuery and compatibility of different programs that weredeveloped using different BDE version and so on.
Abandoning BDE gives one more important advantage - positive effect on performance.
Instead of complex BDE-ODBC drivers system it uses the fastest access - directly to
Microsoft SQL Server.
SDAC provides special Wizard to simplify the conversion of already existing projects. This
Wizard replaces BDE-components in the specified project (dfm-and pas-files) to SDAC.
BDE-components that will be replaced:
TDatabase -> TMSConnection
TQuery -> TMSQuery
TTable -> TMSTable
TStoredProc -> TMSStoredProc
TUpdateSQL -> TMSUpdateSQL
To run the Wizard select BDE/ADO Migration Wizard item in SDAC menu and follow the
instructions. This Wizard is available only for Delphi IDE.
Note: Wizard serves only to simplify routine operations and after the conversion project might
be uncompiled.
Below is a list of properties and methods that cannot be converted automatically. Here you
can find hints for users to simplify manual replacement.

TDatabase© 2019 Devart

46

SQL Server Data Access Components

AliasName - specific BDE property.Not supported by SDAC.
DatabaseName - has a different meaning in BDE and SDAC. In SDAC it means SQL
Server database name. See TCustomMSConnection for details.
Locale - not supported by SDAC.
KeepConnection - not supported by SDAC.
Params - see TCustomMSConnection properties.
Session, SessionAlias, SessionName - SDAC does not need global management of agroup of database connections in an application. So these properties are not supported.
Temporary - has no meaning in SDAC. Additional connections are created but they are notavailable for the user. See FetchAll = False for details.
TraceFlags - see TCustomDASQLMonitor.TraceFlags.
TransIsolation - see IsolationLevel.
Execute - use ExecSQL instead of this method.
FlushSchemaCache - not supported by SDAC.
GetFieldNames - not supported by SDAC.
IsSQLBased - not supported by SDAC. For SQL Server must be always True.
ApplyUpdates - parameters are not supported. To update only specified DataSets, use
ApplyUpdates. Update is performed within a transaction.

TBDEDataSet
BlockReadSize - see FetchRows.
CacheBlobs - SQL Server does not provide service of suspended BLOB loading.
KeySize - specific BDE property. Not supported by SDAC.

TDBDataSet
AutoRefresh - supported through TCustomDADataSet.RefreshOptions.
DBFlags, DBHandle, DBLocate, DBSession, Handle - specific BDE property. Not
supported by SDAC.
SessionName - not supported by SDAC.
UpdateMode - not supported by SDAC. By default, the behaviour corresponds
upWhereKeyOnly. To change this behaviour see TCustomDADataSet.SQLUpdate,
TCustomDADataSet.SQLDelete, TCustomDADataSet.SQLRefresh, andTCustomMSDataSet.Options.CheckRowVersion.

TQueryConstrained - specific BDE property. Not supported by SDAC.

© 2019 DevartGetting Started

47

DataSource - see TCustomDADataSet.MasterSource.
Local - specific BDE property. Not supported by SDAC.
RequestLive - almost all query result sets can be updated. See TMSQuery.UpdatingTable,
TCustomDADataSet.ReadOnly, CanModify, TCustomDADataSet.SQLInsert,
TCustomDADataSet.SQLUpdate, TCustomDADataSet.SQLDelete.
Text - specific BDE property. Not supported by SDAC.

TTableDefaultIndex - not used in SDAC. If you need to sort a table by any field see
TCustomMSTable.OrderFields, TMemDataSet.IndexFieldNames.
Exists, CreateTable, AddIndex, DeleteIndex, StoreDefs, Deletetable, TableType - SDAC
does not allow to create tables using TTable. If you need to create a table execute'CREATE TABLE ...' query or use any special third-party tools.
IndexFieldNames - a list of fields for local sorting. See TMemDataSet.IndexFieldNames.
IndexDefs, IndexFieldCount, IndexFields, IndexFiles, IndexName, GetIndexNames,
GetIndexInfo - Not supported by SDAC.
KeyExclusive - not supported by SDAC. Use SELECT ... FROM .. WHERE ... to get
requested result .
KeyFieldCount - not supported by SDAC as key fields are not used for searching on clientside.
TableLevel - BDE-specific property. Not supported by SDAC.
ApplyRange, CancelRange, EditRangeStart, EditRangeEnd, SetRange - SDAC does notsupport Range.
BatchMove - has no meaning in SQL Server. Use SELECT ... INTO ... syntax to copy
records to server side.
FindKey, FindNearest, GotoCurrent, GotoKey, GotoNearest, EditKey, SetKey - use
TMemDataSet.Locate and TMemDataSet.LocateEx.
GetDetailLinkFields - use TCustomDADataSet.DetailFields,
TCustomDADataSet.MasterFields.
RenameTable - use 'RENAME TABLE ...' script.
ConstraintCallBack, ConstraintsDisabled, DisableConstraints, EnableConstraints - has no
meaning in SQL Server.
FlushBuffers - not supported by SDAC.
Translate - use AnsiToNative and similar functions.

TSession© 2019 Devart

48

SQL Server Data Access Components

SDAC does not need global management of a group of database connections in an
application.

TUpdateSQL
A complete analogue to TMSUpdateSQL.

© 1997-2019
Devart. All Rights
Reserved.

3.4

Request Support

DAC Forum

Provide Feedback

Migration from ADO
SDAC behaviour resembles the one of ADO as much as possible, so migration from ADO to
SDAC shoulв not cause much difficulties. As far as possible, SDAC behaviour
approaches to the behaviour of ADO, so this migration should not cause any serious
difficulties.
It is necessary to note that ADO provides universal data access and, as many universal tools
do, does not specialize on any. loses any specialized one. First of all, it affects
performance. You can see Performance project from SDAC\Demos\Performance to find out
yourself - ADO loses SDAC at different tests from 1.5 to 20 times. Besides, SDAC interface(run-time and design-time) is focused on working with specific features of SQL Server.
SDAC offers special Wizard to simplify the conversion of already existing projects. This
Wizard replaces ADO-components in the specified project (dfm- and pas-files) to SDAC.
ADO-components that will be replaced:
TADOConnection -> TMSConnection
TADOCommand -> TMSSQLTADOTable -> TMSTableTADOQuery -> TMSQueryTADOStoredProc -> TMSStoredProc
To run the Wizard select BDE/ADO Migration Wizard item in SDAC menu and follow the
instructions. This Wizard is available only for Delphi IDE.
Note: Wizard serves only to simplify routine operations and after the conversion project might
be uncompiled.
Below is a list of properties and methods which cannot be converted automatically. Here you
can find hints for users to simplify manual replacement.

© 2019 DevartGetting Started

49

TADOConnection
Attributes - not supported by SDAC. After execution TCustomDAConnection.Commit orTCustomDAConnection.Rollback, Connection is valid.
CommandCount, Commands - not supported by SDAC.
CommandTimeout - must be set separately for each TMSSQL and TCustomMSDataSet.
See TMSSQL.CommandTimeout and TCustomMSDataSet.CommandTimeout.
ConnectionObject - not supported by SDAC.
ConnectionString - SDAC has similar
P:Devart.Sdac.TCustomMSConnection.ConnectString property.
ConnectOptions - not supported by SQL OLE DB provider. Connection is always settled
synchronously.
CursorLocation - must be set separately for each TCustomMSDataSet. See CursorType.
DefaultDatabase - SDAC has similar Database property. The value of Database is always
the same as ConnectString.
Errors not supported by SDAC. Use TMSConnection.OnInfoMessage and EOLEDBError
handling to obtain the requested information.
KeepConnection - not supported by SDAC. Behaviour is similar to
TADOConnection.KeepConnection = True.
Mode not supported by SDAC.
Properties not supported by SDAC.
Provider has no meaning for SDAC, as only SQL Server is supported.
State not supported by SDAC.
Version to determine SDAC version use global variable SDACVersion. To get version of theserver and client use TCustomMSConnection.ServerVersion andTCustomMSConnection.ClientVersion.
BeginTrans use TCustomDAConnection.StartTransaction instead.
Cancel not supported by SDAC, as SQL OLE DB provider does not support asynchronous
setting of connections.
CommitTrans - use TCustomDAConnection.Commit instead.
Execute use TCustomDAConnection.ExecSQL instead.
GetProcedureNames - use TCustomDAConnection.GetStoredProcNames instead.
GetFieldNames - not supported by SDAC, use TMSMetaData instead.
OpenSchema - not supported by SDAC, use TMSMetaData instead.
RollbackTrans - use TCustomDAConnection.Rollback instead.
OnBeginTransComplete, OnCommitTransComplete, OnConnectComplete, OnDisconnect,© 2019 Devart

50

SQL Server Data Access Components

OnExecuteComplete, OnRollbackTransComplete, OnWillConnect, OnWillExecute - notsupported by SDAC.

TADOCommand
CommandObject - not supported by SDAC.
CommandText - use TCustomDASQL.SQL.Text.
CommandType - not supported by SDAC, the behaviour is similar to cmdText.
ConnectionString - use P:Devart.Sdac.TCustomMSConnection.ConnectString instead.
ExecuteOptions - SQL OLE DB provider does not support asynchronous execution of thecommands. If you need to break execution of a query from another thread, use
TMSSQL.BreakExec.
Parameters use TCustomDASQL.Params.
Prepared use TCustomDASQL.Prepare/TCustomDASQL.Unprepare.
Properties, States - not supported by SDAC.
Cancel use TMSSQL.BreakExec call from another thread.

TADOQuery, TADODataSet
BlockReadSize, CacheSize - use FetchRows instead.
ConnectionString - use P:Devart.Sdac.TCustomMSConnection.ConnectString instead.
DesignerData - not supported by SDAC.
EnableBCD use TCustomMSDataSet.Options.EnableBCD.
ExecuteOptions - SQL OLE DB provider does not support asynchronous execution of thecommands. If you need to break execution of a query from another thread, use
TMSSQL.BreakExec.
FilterGroup not supported by SDAC.
Indexname a list of fields for local sorting. See TMemDataSet.IndexFieldNames.
IndexFieldCount, IndexFields - not supported by SDAC.
LockType not supported by SQL Server.
MarshalOptions - not supported by SQL Server.
MaxRecords - not supported by SQL Server.
Parameters use TCustomDADataSet.Params.
Prepared use TCustomDADataSet.Prepare/TMemDataSet.UnPrepare.
Properties not supported by SDAC.
RecordSet, RecordSetState - not supported by SDAC.
RecordSize not supported by SDAC.
RecordStatus - use TMemDataSet.UpdateStatus.

© 2019 DevartGetting Started

51

Sort use TMemDataSet.IndexFieldNames.
ExecSQL use TCustomDADataSet.Execute instead.
CancelBatch - not supported by SDAC.
Clone not supported by SDAC.
DeleteRecords - not supported by SDAC.
FilterOnBookmark - use Filter, FilterSQL instead.
GetBlobFieldData - not supported by SDAC.
GetDetailLinkFields - use TCustomDADataSet.DetailFields.
IsSequenced - not supported by SDAC.
LoadFromFile, SaveToFile - not supported by SDAC.
NextRecordset - use TCustomMSDataSet.OpenNext.
Requery TDataSet.Refresh.
Seek not supported by SQL OLE DB provider.
Supports not supported by SDAC.
UpdateBatch - not supported by SDAC.
OnEndOfRecordset, OnFetchComplete, OnFetchProgress, OnFieldChangeComplete,
OnMoveComplete, OnRecordChangeComplete, OnRecordsetChangeComplete,
OnRecordsetCreate, OnWillChangeField, OnWillChangeRecord, OnWillChangeRecordset,
OnWillMove - specific ADO properties, not supported by SDAC.

TADOStoredProc
ProcedureName - use TCustomMSStoredProc.StoredProc.

TADOTable
TableDirect - not supported by MS OLE DB provider.

© 1997-2019
Devart. All Rights
Reserved.

3.5

Request Support

DAC Forum

Logging on to SQL ServerThis tutorial describes how to connect to SQL Server.
Contents
1. Requirements
2. General information
3. Creating Connection
3.1 Design time creation
3.1.1 Using TMSConnection Editor© 2019 Devart

Provide Feedback

52

SQL Server Data Access Components

3.1.2 Using Object Inspector
3.2 Run time creation
4. Opening connection
5. Closing connection
6. Modifying connection
7. Additional information
8. See Also

Requirements
In order to connect to SQL Server, you need the server itself running, SDAC installed, andIDE running. Also, you need to know the server name (if the server is run on the remotecomputer), the port that the server listens to (if you use not the 1433 standard port), theauthentication mode, and the database name. If SQL Server Authentication is used, you alsoneed to know the user name and the password.

General information
To establish connection to the server, you have to provide some connection parameters to
SDAC. This information is used by the TMSConnection component to establish connection to
the server. The parameters are represented by the properties of the TMSConnection
component (Server, Database, Authentication, Username, Password). If Windows
Authentication is used, the Username and Password properties are ignored.
Note: All these options can be specified at once using the ConnectString property.
There are two ways to connect to SQL Server: using the OLE DB provider and using the SQL
Server Native Client provider. This is controlled by the TMSConnection.Options.Provider
property. It indicates the provider that is used for connection to SQL Server. By default, theProvider property is set to prAuto, which means that an available provider with the mostrecent version is used. In this case, SDAC looks for an available provider in the following
sequence: Native Client 11, Native Client 10, Native Client 9, OLEDB. If Provider is set to
prNativeClient, SDAC looks for an available provider in the following sequence: Native Client
11, Native Client 10, Native Client 9. The first found provider from the sequence is used. If
Provider is set to prSQL, SDAC uses the OLEDB provider.
If Provider is set to prCompact, SDAC uses the SQL Server Compact provider. For more
information about connecting to SQL Server Compact, please refer to the "Connecting To
SQL Server Compact" topic.
Note: If SDAC cannot find the choosen provider, the "Required provider is not installed" error© 2019 DevartGetting Started

53

is generated.

Creating Connection
Design time creation
The following assumes that you have the IDE running, and you are currently focused on theform designer.
1. Open the Component palette and find the TMSConnection component in the SQL Server
Access category.
2. Double-click on the component. Note that the new object appears on the form. If this is thefirst time you create TMSConnection in this application, it is named MSConnection1.
After you have done these steps, you should set up the newly created MSConnection1
component. You can do this in two ways:

Using TMSConnection Editor
1. Double-click on the MSConnection1 object.
2. In the Server edit box specify a DNS name or IP address of the computer, where SQL
Server resides. If not the 1433 standard port must be used, it can be specified in the Server
edit box in the following format: server,port (for example, localhost,1433).
3. Choose the authentication mode, SQL Server or Windows.
4. If SQL Server Authentication is chosen, specify a login (for example, sa) in the Username
edit box.
5. If SQL Server Authentication is chosen, specify a password (for example, password ) in
the Password edit box. If a login does not have a password, leave the Password edit box
blank.
6. In the Database edit box specify the database name (for example, master). If Database is
not specified, the master system database is used.
Note: If SQL Server Authentication is chosen and Username and Password are notspecified, the sa user name and the blank password are used.

Using Object Inspector
1. Click on the MSConnection1 object and press F11 to focus on object's properties.
2. Set the Server property to a DNS name or IP address of the computer, where SQL Server
resides. If not the 1433 standard port must be used, it can be specified in the Server
property in the following format: server,port (for example, localhost,1433).

© 2019 Devart

54

SQL Server Data Access Components

3. In the Authentication property choose the authentication mode, SQL Server or Windows.
4. If SQL Server Authentication is chosen, specify a login in the Username property (forexample, sa).
5. If SQL Server Authentication is chosen, specify a password in the Password property (forexample, password). If a login does not have a password, leave the Password property
blank.
6. In the Database property specify the database name (for example, master ). If Databaseis not specified, the master system database is used.
Note: If SQL Server Authentication is chosen and Username and Password are notspecified, the sa user name and the blank password are used.

Run time creation
The same operations performed in runtime look as follows:[Delphi]varcon: TMSConnection;
begin
con := TMSConnection.Create(nil);try
con.Server := 'server';con.Authentication := auServer;con.Username := 'username';
con.Password := 'password';
con.Database := 'database';con.LoginPrompt := False; // to prevent showing of the connection dialog
con.Open;
finallycon.Free;end;
end;
Note: To run this code, you have to add the MSAccess and OLEDBAccess units to the
USES clause of your unit.

[C++Builder]{
TMSConnection* con = new TMSConnection(NULL);
try{
con->Server = "server";con->Authentication = auServer;
con->Username = "username";con->Password = "password";
con->Database = "database";© 2019 DevartGetting Started

55

con->LoginPrompt = False; // to prevent showing of the connection dialog
con->Open();}__finally{con->Free();}}Note: To run this code, you have to include the MSAccess.hpp header file to your unit.
And using the ConnectString property:[Delphi]varcon: TMSConnection;
begin
con := TMSConnection.Create(nil);try
con.ConnectString := 'Data Source=server;User ID=username;Password=passw
con.LoginPrompt := False; // to prevent showing of the connection dialog
con.Open;
finallycon.Free;end;
end;
Note: To run this code, you have to add the MSAccess units to the USES clause of your unit.

[C++ Builder]{

TMSConnection* con = new TMSConnection(NULL);
try{
con->ConnectString = "Data Source=server;User ID=username;Password=passw
con->LoginPrompt = False; // to prevent showing of the connection dialog
con->Open();}__finally{con->Free();}}Note: To run this code, you have to include the MSAccess.hpp header file to your unit.

Opening connection
As you can see above, opening a connection at run-time is as simple as calling of the Open© 2019 Devart

56

SQL Server Data Access Components

method:[Delphi]con.Open;[C++ Builder]con->Open();
Another way to open a connection at run-time is to set the Connected property to True:[Delphi]con.Connected := True;[C++ Builder]con->Connected = True;
This way can be used at design-time as well. Of course, MSConnection1 must have valid
connection options assigned earlier. When you call Open, SDAC tries to find the host andconnect to the server. If any problem occurs, it raises an exception with brief explanation onwhat is wrong. If no problem is encountered, SDAC tries to establish connection. Finally,
when connection is established, the Open method returns and the Connected property ischanged to True.

Closing connection
To close a connection, call its Close method, or set its Connected property to False:[Delphi]con.Close;[C++ Builder]con.Close();or:[Delphi]con.Connected := False;[C++ Builder]con.Connected = False;

Modifying connection
You can modify connection by changing properties of the TMSConnection object. Keep inmind that while some of the properties can be altered freely, most of them close connection
when the a value is assigned. For example, if you change Server property, it is closed
immediately, and you have to reopen it manually.

© 2019 DevartGetting Started

57

Additional information
SDAC has a wide set of features you can take advantage of. The following list enumerates
some of them, so you can explore the advanced techniques to achieve better performance,balance network load or enable additional capabilities:
Local Failover
Connection Pooling
Disconnected Mode
Data Type Mapping
Notifications
Table-Valued Parameters
FILESTREAM
User-Defined Functions

See Also
TMSCConnection
ServerAuthentication
Database
Username
Password
LoginPrompt© 1997-2019
Devart. All Rights
Reserved.

3.6

Request Support

DAC Forum

Logging on to SQL Server Compact
This tutorial describes how to connect to SQL Server Compact.
Contents
1. Requirements
2. General information
3. Creating Connection
3.1. Design time creation
3.1.1. Using Connection Editor
3.1.2. Using Object Inspector
3.2. Run time creation© 2019 Devart

Provide Feedback

58

SQL Server Data Access Components

4. Opening connection
5. Closing connection
6. Modifying connection
7. Additional information
8. See Also

Requirements
In order to connect to SQL Server Compact, you need the server itself installed, SDAC
installed, and IDE running. In addition, you need to know the full path to the database file(.SDF). If a database is password-protected, you also need to know the password.

General information
It is possible to connect to SQL Server Compact using both TMSCompactConnection and
TMSConnection components. To establish connection to the server, you have to provide
some connection parameters to SDAC. This information is used by the
TMSCompactConnection or TMSConnection component to establish connection to theserver. The parameters are represented by the properties of the TMSCompactConnection or
TMSConnection component (Database, Password). If TMSConnection is used, the
TMSConnection.Options.Provider property must be set to prCompact.
To choose a version of SQL Server Compact you want to work with using
TMSCompactConnection, you can use the
TMSCompactConnection.Options.CompactVersion property. Here is a list of possible values:
cvAuto - an available SQL Server Compact provider with the most recent version is used.
In this case, SDAC looks for an available provider in the following sequence: SQL Server
Compact 4.0 , SQL Server Compact 3.5 , SQL Server Compact 3.1. The first foundprovider from the sequence is used.
cv40 - SQL Server Compact 4.0 is used.
cv35 - SQL Server Compact 3.5 is used.
cv30 - SQL Server Compact 3.1 is used.
To choose a version of SQL Server Compact you want to work with using TMSConnection,
you can use the Provider connection string option in the TMSConnection.ConnectString
property. Here is a list of possible values:
Provider=MICROSOFT.SQLSERVER.MOBILE.OLEDB.4.0 - SQL Server Compact 4.0
is usedProvider=MICROSOFT.SQLSERVER.MOBILE.OLEDB.3.5 - SQL Server Compact 3.5
is used© 2019 DevartGetting Started

59

Provider=MICROSOFT.SQLSERVER.MOBILE.OLEDB.3.0 - SQL Server Compact 3.1
is usedNote: If a database exists before a connection attempt, SDAC tries to determine the correct
version of SQL Server Compact to use by reading it from the database itself. If SDAC
obtaines the version of SQL Server Compact from the database, an appropriate provider isused.
Note: If SDAC cannot find the choosen provider, the "Required provider is not installed" error
is generated.

Creating Connection
Design time creation
The following assumes that you have IDE running, and you are currently focused on the form
designer.
TMSCompactConnection:
1. Open the Component palette and find the TMSCompactConnection component in the SQL
Server Access category.
2. Double-click on the component. Note that a new object appears on the form. If this is thefirst time you create TMSCompactConnection in this application, it is named
MSCompactConnection1.
TMSConnection:
1. Open the Component palette and find the TMSConnection component in the SQL Server
Access category.
2. Double-click on the component. Note that a new object appears on the form. If this is thefirst time you create TMSConnection in this application, it is named MSConnection1.
After you have done these steps, you should set up the newly created
MSCompactConnection1 or MSConnection1 component. You can do this in two ways:

Using Connection Editor
TMSCompactConnection:
1. Double-click on the TMSCompactConnection object.
2. In the Database edit box specify the database name (for example, C:\test.sdf). If thespecified database does not exist, it will be created on a connection attempt.

© 2019 Devart

60

SQL Server Data Access Components

3. If the specified database is password-protected, specify the password in the Password
edit box.

Using Object Inspector
TMSCompactConnection:
1. Click on the MSCompactConnection1 object and press F11 to focus on the object
properties.
2. In the Database property specify the database name (for example, C:\test.sdf). If thespecified database does not exist, it will be created on connection attempt.
3. If the specified database is password-protected, specify the password in the Password
property.
TMSConnection:
1. Click on the MSConnection1 object and press F11 to focus on the object properties.
2. Set the Options.Provider property to prCompact.
3. In the Database property specify the database name (for example, C:\test.sdf). If thespecified database does not exist, it will be created on connection attempt.
4. If the specified database is password-protected, specify the password in the Password
property.

Run time creation
The same operations performed in runtime look as follows:
TMSCompactConnection:[Delphi]procedure TMainForm.ButtonConnectClick(Sender: TObject);var
con: TMSCompactConnection;
begin
con := TMSCompactConnection.Create(nil);trycon.Options.CompactVersion := cv40;
con.Database := 'database'; // if the database does not exist, it will bcon.Password := 'password'; // if the database is password-protectedcon.LoginPrompt := False; // to prevent showing of the connection dialog
con.Open;
finallycon.Free;end;
end;
Note: To run this code, you have to add the MSCompactConnection and OLEDBAccessunits to the USES clause of your unit.

© 2019 DevartGetting Started

61[C++Builder]

void __fastcall TMainForm::ButtonConnectClick(TObject *Sender){
TMSCompactConnection* con = new TMSCompactConnection(NULL);
try{
con->Options->CompactVersion = cv40;
con->Database = "database"; // if the database does not exist, it will bcon->Password = "password"; // if the database is password-protectedcon->LoginPrompt = False; // to prevent showing of the connection dialog
con->Open();}__finally{con->Free();}}Note: To run this code, you have to include the MSCompactConnection.hpp header file toyour unit.
TMSConnection:[Delphi]procedure TMainForm.ButtonConnectClick(Sender: TObject);var
con: TMSConnection;
begin
con := TMSConnection.Create(nil);try
con.ConnectString := 'Provider=MICROSOFT.SQLSERVER.MOBILE.OLEDB.4.0';
con.Database := 'database'; // if the database does not exist, it will bcon.Password := 'password'; // if the database is password-protectedcon.LoginPrompt := False; // to prevent showing of the connection dialog
con.Open;
finallycon.Free;end;
end;
Note: To run this code, you have to add the MSAccess unit to the USES clause of your unit.

[C++ Builder]
void __fastcall TMainForm::ButtonConnectClick(TObject *Sender){
TMSConnection* con = new TMSConnection(NULL);
try© 2019 Devart

62

SQL Server Data Access Components{

con->ConnectString = "Provider=MICROSOFT.SQLSERVER.MOBILE.OLEDB.4.0";
con->Database = "database"; // if the database does not exist, it will bcon->Password = "password"; // if the database is password-protectedcon->LoginPrompt = False; // to prevent showing of the connection dialog
con->Open();}__finally{con->Free();}}Note: To run this code, you have to include the MSAccess.hpp header file to your unit.

Opening connection
As you can see above, opening connection at run-time is as simple as calling of the Openmethod:[Delphi]con.Open;[C++ Builder]con->Open();
Another way to open connection at run-time is to set the Connected property to True:[Delphi]con.Connected := True;[C++ Builder]con->Connected = True;
This way can be used at design-time as well. Of course, connection(TMSCompactConnection or TMSConnection) must have valid connection options assigned
earlier. When you call Open, SDAC tries to open the database. If any problem occurs, it
raises an exception with brief explanation on what is wrong. If no problem is encountered andthe database is opened, the Open method returns and the Connected property is changed to
True.

Closing connection
To close connection, call its Close method, or set its Connected property to False:[Delphi]con.Close;[C++ Builder]© 2019 DevartGetting Started

63

con.Close();or:[Delphi]con.Connected := False;[C++ Builder]con.Connected = False;

Modifying connection
You can modify connection by changing the properties of the TMSCompactConnection or
TMSConnection component. Keep in mind that while some of the properties can be alteredfreely, most of them close connection when a new value is assigned. For example, if youchange the Server property, it is closed immediately, and you have to reopen it manually.

Additional information
SDAC has a wide set of features you can take advantage of. The following list enumerates
some of them, so you can explore the advanced techniques to achieve better performance,balance network load or enable additional capabilities:
Connection Pooling
Disconnected Mode
Data Type Mapping

See Also
TMSCompactConnection
TMSConnection
ServerAuthentication
Database
Username
Password
LoginPrompt
TMSCompactConnectionOptions.CompactVersion
TCustomMSConnection.ConnectString© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

64

3.7

SQL Server Data Access Components

Creating Database Objects
This tutorial describes how to create tables, stored procedures and other objects on SQL
Server.
1. Requirements
2. General information
3. Creating tables
o 3.1 Design-time creationo 3.2 Run-time creation
4. Creating Stored Procedureso 4.1 Design Time Creationo 4.2 Run Time Creation
5. Additional information

Requirements
In order to create database objects you have to connect to SQL Server. This process is
described in details in the tutorials "Connecting To SQL Server" and "Connecting To SQLServer Compact".

General information
Database objects are created using Data Definition Language (DDL), which is a part of SQL.
The DDL statements can be executed on server by an account that has the necessaryprivileges. There are two ways to create database objects. You can build DDL statements
manually and execute them using a component like TMSSQL. Another way is to use visual
database tools like dbForge Studio for SQL Server or Microsoft SQL Server Management
Studio. This topic covers the first way - using components.
There are two ways to execute DDL statements in components like TMSSQL: in design-timeand in run-time. Both these ways are described below.
Note: The following assumes that you have the IDE running, you are currently focused on theform designer, and you have already set up the TMSConnection or TMSCompactConnection
component on the form.

Creating tables
To create tables, the TMSSQL component is used here.

Design-time creation© 2019 DevartGetting Started

65Open the Component palette and find the TMSSQL component in the SQL Server Access
category.
Double-click on the component. Note that a new object appears on the form. If this is thefirst time you create TMSSQL in this application, it is named MSSQL1. Note that the
MSSQL1.Connection property is already set to an existent (on the form) connection.
Double-click on the MSSQL1 object.
Type the following lines:
CREATE TABLE dept (deptno INT PRIMARY KEY,
dname VARCHAR(14),loc VARCHAR(13));
CREATE TABLE emp (
empno INT IDENTITY(1,1) PRIMARY KEY,
ename VARCHAR(10),job VARCHAR(9),mgr INT,
hiredate DATE,
sal FLOAT,
comm FLOAT,
deptno INT);
Click on the Execute button. This will create two tables that we will use for tutorial purposes.

Run-time creation
Same operations performed in runtime look as follows:[Delphi]var
sql: TMSSQL;
begin
sql := TMSSQL.Create(nil);try
sql.Connection := con; // con is either TMSConnection or TMSCompactConne
sql.SQL.Clear;sql.SQL.Add('CREATE TABLE dept (');
sql.SQL.Add(' deptno INT PRIMARY KEY,');
sql.SQL.Add(' dname VARCHAR(14),');
sql.SQL.Add(' loc VARCHAR(13)');
sql.SQL.Add(');');
sql.SQL.Add('CREATE TABLE emp (');
sql.SQL.Add(' empno INT IDENTITY(1,1) PRIMARY KEY,');
sql.SQL.Add(' ename VARCHAR(10),');
sql.SQL.Add(' job VARCHAR(9),');
sql.SQL.Add(' mgr INT,');
sql.SQL.Add(' hiredate DATE,');© 2019 Devart

66

SQL Server Data Access Components

sql.SQL.Add(' sal FLOAT,');
sql.SQL.Add(' comm FLOAT,');
sql.SQL.Add(' deptno INT');
sql.SQL.Add(');');
sql.Execute;finallysql.Free;end;
end;[C++Builder]{

TMSSQL* sql = new TMSSQL(NULL);
try{sql->Connection = con; // con is either TMSConnection or TMSCompactConne
sql->SQL->Clear();sql->SQL->Add("CREATE TABLE dept (");
sql->SQL->Add(" deptno INT PRIMARY KEY,");sql->SQL->Add(" dname VARCHAR(14),");
sql->SQL->Add(" loc VARCHAR(13)");sql->SQL->Add(");");
sql->SQL->Add("CREATE TABLE emp (");
sql->SQL->Add(" empno INT IDENTITY(1,1) PRIMARY KEY,");sql->SQL->Add(" ename VARCHAR(10),");
sql->SQL->Add(" job VARCHAR(9),");
sql->SQL->Add(" mgr INT,");
sql->SQL->Add(" hiredate DATE,");sql->SQL->Add(" sal FLOAT,");
sql->SQL->Add(" comm FLOAT,");
sql->SQL->Add(" deptno INT");sql->SQL->Add(");");
sql->Execute();}__finally{sql->Free();}}Creating Stored Procedures
To create tables, the TMSScript component is used here.

Design-time creation
Open the Component palette and find the TMSScript component in the SQL Server Access
category.
Double-click on the component. Note that a new object appears on the form. If this is thefirst time you create TMSScript in this application, it is named MSScript1. Note that the
MSScript1.Connection property is already set to existent (on the form) connection.
Double-click on the MSScript1 object.
© 2019 DevartGetting Started

67

Type the following lines:

CREATE PROCEDURE [Ten Most High-Paid Employees]
AS
BEGIN
SET ROWCOUNT 10
SELECT emp.ename AS TenMostHighPaidEmployees, emp.sal FROM emp ORDER BY em
SET ROWCOUNT 0
END;/
CREATE PROCEDURE GetEmpNumberInDept@deptno INT,
@empnumb INT OUT
AS
BEGIN
SELECT @empnumb = count(*) FROM emp WHERE deptno = @deptno;
END/
Click on the Execute button. This will create five stored procedures that we will use fortutorial purposes.

Run-time creation
The same operations performed in runtime look as follows:[Delphi]var
script: TMSScript;
begin
script := TMSScript.Create(nil);tryscript.Connection := con; // con is either TMSConnection or TMSCompactCo
script.SQL.Clear;
script.SQL.Add('CREATE PROCEDURE [Ten Most High-Paid Employees]');script.SQL.Add('AS');
script.SQL.Add('BEGIN');
script.SQL.Add(' SET ROWCOUNT 10');
script.SQL.Add(' SELECT emp.ename AS TenMostHighPaidEmployees, emp.sal
script.SQL.Add(' SET ROWCOUNT 0');script.SQL.Add('END');
script.SQL.Add('/');
script.SQL.Add('CREATE PROCEDURE GetEmpNumberInDept');
script.SQL.Add('@deptno INT,');
script.SQL.Add('@empnumb INT OUT');
script.SQL.Add('AS');
script.SQL.Add('BEGIN');
script.SQL.Add(' SELECT @empnumb = count(*) FROM emp WHERE deptno = @descript.SQL.Add('END');
script.SQL.Add('/');
script.Execute;© 2019 Devart

68

SQL Server Data Access Components

finally
script.Free;
end;
end;
Note: To run this code, you have to add the MSScript unit to the USES clause of your unit.
[C++Builder]{

TMSScript* script = new TMSScript(NULL);
try{
script->Connection = con; // con is either TMSConnection or TMSCompactCo
script->SQL->Clear();script->SQL->Add("CREATE PROCEDURE [Ten Most High-Paid Employees]");script->SQL->Add("AS");
script->SQL->Add("BEGIN");
script->SQL->Add(" SET ROWCOUNT 10");
script->SQL->Add(" SELECT emp.ename AS TenMostHighPaidEmployees, emp.sa
script->SQL->Add(" SET ROWCOUNT 0");script->SQL->Add("END");
script->SQL->Add("/");
script->SQL->Add("CREATE PROCEDURE GetEmpNumberInDept");
script->SQL->Add("@deptno INT,");
script->SQL->Add("@empnumb INT OUT");
script->SQL->Add("AS");
script->SQL->Add("BEGIN");
script->SQL->Add(" SELECT @empnumb = count(*) FROM emp WHERE deptno = @script->SQL->Add("END");
script->SQL->Add("/");
script->Execute();}__finally{
script->Free();}}Note: To run this code, you have to include the MSScript.hpp header file to your unit.

Additional information
Actually, there are lots of ways to create database objects on server. Any tool or component
that is capable of running a SQL query, can be used to manage database objects. For
example, TMSSQL suits fine for creating objects one by one, while TMSScript is designed forexecuting series of DDL/DML statements. For information on DDL statements syntax refer tothe SQL Server documentation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartGetting Started

3.8

69

Deleting Data From Tables
This tutorial describes how to delete data from tables using the TMSQuery and TMSTable
components.
1. Requirements
2. General information
3. Using DataSet Functionality
4. Building DML Statements Manuallyo 4.1 DML Statements With Parameterso 4.2 DML Statements As Plain Text
5. Additional Information

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact"), how to create necessary objects
on the server (tutorial "Creating Database Objects"), and how to insert data to created tables(tutorial "Inserting Data Into Tables").

General information
Data on server can be deleted using Data Manipulation Language (DML), which is a part of
SQL. DML statements can be executed on server by an account that has necessaryprivileges. There are two ways to manipulate a database. You can build DML statements
manually and run them within some component like TMSQuery. Another way is to use thedataset functionality (the Delete method) of the TMSQuery and TMSTable components. We
will discuss both ways. The goal of this tutorial is to delete a record in the table dept.

Using DataSet Functionality
The Delete method of the TMSQuery and TMSTable components allows deleting data without
using DML statements. DML statements are generated by SDAC components internally. The
code below demonstrates using this method:[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// retrieve data
q.SQL.Text := 'SELECT * FROM dept';© 2019 Devart

70

SQL Server Data Access Components

q.Open;// delete the current record
q.Delete;
finallyq.Free;end;
end;[C++Builder]{
TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// retrieve data
q->SQL->Text = "SELECT * FROM dept";
q->Open();// delete the current record
q->Delete();}__finally{q->Free();}}

Building DML Statements Manually
DML Statements can contain plain text and text with parameters. This section describes bothways.

DML Statements With Parameters[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// set SQL query for delete record
q.SQL.Clear;
q.SQL.Add('DELETE FROM dept WHERE deptno = :deptno;');// set parameters
q.ParamByName('deptno').AsInteger := 10;// execute query
q.Execute;finallyq.Free;end;
end;© 2019 DevartGetting Started

71[C++Builder]{
TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// set SQL query for delete record
q->SQL->Clear();q->SQL->Add("DELETE FROM dept WHERE deptno = :deptno;");// set parameters
q->ParamByName("deptno")->AsInteger = 10;// execute queryq->Execute();}__finally{q->Free();}}

DML Statements As Plain Text
[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// set SQL query for delete record
q.SQL.Clear;
q.SQL.Add('DELETE FROM dept WHERE deptno = 10;');// execute query
q.Execute;finallyq.Free;end;
end;[C++Builder]{
TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// set SQL query for delete record
q->SQL->Clear();q->SQL->Add("DELETE FROM dept WHERE deptno = 10;");// execute queryq->Execute();© 2019 Devart

72

SQL Server Data Access Components}__finally{q->Free();}}

Additional Information
It is also possible to use stored procedures for deleting data. In this case, all data
manipulation logic is defined on server. You can find more about using stored procedures inthe tutorial "Stored Procedures".

© 1997-2019
Devart. All Rights
Reserved.

3.9

Request Support

DAC Forum

Provide Feedback

Inserting Data Into Tables
This tutorial describes how to insert data into tables using the TMSQuery and TMSTable
components.
1. Requirements
2. General information
3. Design Time
4. Run Timeo 4.1 Using DataSet Functionalityo 4.2 Building DML Statements Manually
4.2.1 DML Statements With Parameters
4.2.2 DML Statements As Plain Text
5. Additional Information

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact") and that necessary objects are
already created on the server (tutorial "Creating Database Objects").

General information
Data on server can be inserted using Data Manipulation Language (DML), which is a part of
SQL. DML statements can be executed on server by an account that has necessaryprivileges. There are two ways to manipulate a database. You can build DML statements
manually and run them within some component like TMSQuery. Another way is to use thedataset functionality (the Insert, Append, and Post methods) of the TMSQuery and TMSTable© 2019 DevartGetting Started

73

components. We will discuss both ways.
The goal of this tutorial is to insert the following data into tables dept and emp:
Table dept

deptno
10
20
30
40

dname
ACCOUNTINGRESEARCH
SALES
OPERATIONS

loc
NEW YORKDALLASCHICAGOBOSTON

Table emp

ename
SMITH
ALLEN
WARD
JONES
MARTIN
BLAKE
CLARK
SCOTT
KING
TURNER
ADAMS
JAMES
FORD
MILLER

job
mgr
CLERK
7902
SALESMA
7698
N
SALESMA
7698
N
MANAGER 7839
SALESMA
7698
N
MANAGER 7839
MANAGER 7839
ANALYST 7566
PRESIDEN
NULL
T
SALESMA
7698
N
CLERK
7788
CLERK
7698
ANALYST 7566
CLERK
7782

hiredatesal
17.12.1980 800

comm
NULL

deptno20

20.02.1981 1600

300

30

22.02.1981 1250

500

30

02.04.1981 2975

NULL

20

28.09.1981 1250

1400

30

01.05.1981 2850
09.06.1981 2450
13.07.1987 3000

NULL
NULL
NULL

30
10
20

17.11.1981 5000

NULL

10

08.09.1981 1500

030

13.07.1987 1100
03.12.1981 950
03.12.1981 3000
23.01.1982 1300

NULL
NULL
NULL
NULL

20
30
20
10

Note: The empno field of the emp table is an IDENTITY(1,1) (i.e. autoincrement) field, so its
value is filled automatically by the server.

Design time
Open the Component palette and find the TMSQuery component in the SQL Server Access
category.
© 2019 Devart

74

SQL Server Data Access Components

Double-click on the component. Note that a new object appears on the form. If this is thefirst time you create TMSQuery in this application, it is named MSQuery1. Note that the
MSQuery1.Connection property is already set to an existent (on the form) connection.
Double-click on the MSQuery1 object.
Type the following lines:
INSERT INTO dept VALUES (10,'ACCOUNTING','NEW YORK');
Press the Execute button.
Performing these steps adds a new record to the dept table.

Run time
Using DataSet Functionality
The Insert, Append, and Post methods of the TMSQuery and TMSTable components allow
inserting data not using DML statements. DML statements are generated by SDAC
components internally. The difference between the Append and Insert methods is that Append
creates a new empty record in the end of a dataset, when Insert creates it in the position of
the current record of a dataset. The code below demonstrates using these methods:[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);tryq.Connection := con; // con is either TMSConnection or TMSCompactConnect
q.SQL.Text := 'SELECT * FROM dept';
q.Open;q.Append;
q.FieldByName('deptno').AsInteger := 10;
q.FieldByName('dname').AsString := 'ACCOUNTING';
q.FieldByName('loc').AsString := 'NEW YORK';
q.Post;finallyq.Free;end;
end;[C++Builder]{

TMSQuery* q = new TMSQuery(NULL);
try{q->Connection = con; // con is either TMSConnection or TMSCompactConnectq->SQL->Text = "SELECT * FROM dept";
q->Open();© 2019 DevartGetting Started

75

q->Append();q->FieldByName("deptno")->AsInteger = 10;
q->FieldByName("dname")->AsString = "ACCOUNTING";
q->FieldByName("loc")->AsString = "NEW YORK";
q->Post();}__finally{q->Free();}}

Building DML Statements Manually
DML Statements can contain plain text and text with parameters. This section describes bothways.

DML Statements With Parameters[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);tryq.Connection := con; // con is either TMSConnection or TMSCompactConnect
q.SQL.Clear;
q.SQL.Add('INSERT INTO dept(deptno, dname, loc) VALUES (:deptno, :dname,q.ParamByName('deptno').AsInteger := 10;
q.ParamByName('dname').AsString := 'ACCOUNTING';
q.ParamByName('loc').AsString := 'NEW YORK';
q.Execute;finallyq.Free;end;
end;[C++Builder]{

TMSQuery* q = new TMSQuery(NULL);
try{q->Connection = con; // con is either TMSConnection or TMSCompactConnectq->SQL->Clear();q->SQL->Add("INSERT INTO dept(deptno, dname, loc) VALUES (:deptno, :dnamq->ParamByName("deptno")->AsInteger = 10;
q->ParamByName("dname")->AsString = "ACCOUNTING";
q->ParamByName("loc")->AsString = "NEW YORK";
q->Execute();}__finally{q->Free();© 2019 Devart

76

SQL Server Data Access Components}}

DML Statements As Plain Text
[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);tryq.Connection := con; // con is either TMSConnection or TMSCompactConnect
q.SQL.Clear;
q.SQL.Add('INSERT INTO dept(deptno, dname, loc) VALUES (10,''ACCOUNTING'
q.Execute;finallyq.Free;end;
end;[C++Builder]{

TMSQuery* q = new TMSQuery(NULL);
try{q->Connection = con; // con is either TMSConnection or TMSCompactConnectq->SQL->Clear();q->SQL->Add("INSERT INTO dept(deptno, dname, loc) VALUES (10,'ACCOUNTING
q->Execute();}__finally{q->Free();}}

Additional Information
Actually, there are lots of ways to insert data into tables. Any tool or component capable ofrunning a SQL query can be used to manage data. Some components are better for
performing certain tasks. For example, TMSLoader is the fastest way to insert data,
TMSScript is designed for executing series of statements one by one.
It is also possible to use stored procedures for inserting data. In this case, all data
manipulation logic is defined on the server. You can find more about using stored proceduresin the tutorial "Stored Procedures".

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartGetting Started

3.10

77

Retrieving Data
1. Requirements
2. General Information
3. TMSQuery
4. TMSTable
5. Additional information

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact"), how to create necessary objects
on the server (tutorial "Creating Database Objects"), and how to insert data to created tables(tutorial "Inserting Data Into Tables").

General information
As we know, an original function of any database application is establishing connection to adata source and working with data contained in it. SDAC provides several components thatcan be used for data retrieving, such as TMSQuery and TMSTable. We will discuss data
retrieving using these components.
The goal of this tutorial is to retrieve data from a table dept.

TMSQuery
The following code demonstrates retrieving of data from the dept table using the TMSQuerycomponent:[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// retrieve data
q.SQL.Text := 'SELECT * FROM dept';
q.Open;// shows the number of records obtained from the server
ShowMessage(IntToStr(q.RecordCount));
finallyq.Free;end;
end;[C++Builder]© 2019 Devart

78

SQL Server Data Access Components{
TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// retrieve data
q->SQL->Text = "SELECT * FROM dept";
q->Open();// shows the number of records obtained from the server
ShowMessage(IntToStr(q->RecordCount));}__finally{q->Free();}}

TMSTable
The following code demonstrates retrieving of data from the dept table using the TMSTable
component:[Delphi]vartbl: TMSTable;
begin
tbl := TMSTable.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
tbl.Connection := con;// retrieve data
tbl.TableName := 'dept';
tbl.Open;// shows the number of records obtained from the server
ShowMessage(IntToStr(tbl.RecordCount));
finallytbl.Free;end;
end;[C++Builder]{
TMSTable* tbl = new TMSTable(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
tbl->Connection = con;// retrieve datatbl->TableName = "dept";tbl->Open();// shows the number of records obtained from the server
ShowMessage(IntToStr(tbl->RecordCount));}© 2019 DevartGetting Started

79__finally{tbl->Free();}}

Additional Information
It is also possible to use stored procedures for data retrieving. In this case, all data
manipulation logic is defined on server. You can find more about using stored procedures inthe tutorial "Stored Procedures".

© 1997-2019
Devart. All Rights
Reserved.

3.11

Request Support

DAC Forum

Provide Feedback

Modifying Data
This tutorial describes how to modify data into tables using the TMSQuery and TMSTable
components.
1. Requirements
2. General information
3. Using DataSet Functionality
4. Building DML Statements Manuallyo 4.1 DML Statements With Parameterso 4.2 DML Statements As Plain Text
5. Additional Information

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact"), how to create necessary objects
on the server (tutorial "Creating Database Objects"), and how to insert data to created tables(tutorial "Inserting Data Into Tables").

General information
Data on server can be modified using Data Manipulation Language (DML), which is a part of
SQL. DML statements can be executed on server by an account that has necessaryprivileges. There are two ways to manipulate a database. You can build DML statements
manually and run them within some component like TMSQuery. Another way is to use thedataset functionality (the Edit and Post methods) of the TMSQuery and TMSTable
components. We will discuss both ways. The goal of this tutorial is to modify the following
record of the table dept:© 2019 Devart

80

SQL Server Data Access Components

10

ACCOUNTINGNEW YORKRESEARCHLOS ANGELES

to make it look as follows:

10

Using DataSet Functionality
The Edit and Post methods of the TMSQuery and TMSTable components allow deleting data
without using DML statements. DML statements are generated by SDAC components
internally. The code below demonstrates using these methods:[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// retrieve data
q.SQL.Text := 'SELECT * FROM dept';
q.Open;// to make the record with deptno=10 the current record
q.FindKey([10]);// modify record
q.Edit;q.FieldByName('dname').AsString := 'RESEARCH';
q.FieldByName('loc').AsString := 'LOS ANGELES';
q.Post;finallyq.Free;end;
end;[C++Builder]{
TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// retrieve data
q->SQL->Text = "SELECT * FROM dept";
q->Open();// to make the record with deptno=10 the current record
q->FindKey(ARRAYOFCONST((10)));// modify record
q->Edit();q->FieldByName("dname")->AsString = "RESEARCH";
q->FieldByName("loc")->AsString = "LOS ANGELES";
q->Post();}__finally{© 2019 DevartGetting Started

81

q->Free();}}

Building DML Statements Manually
DML Statements can contain plain text and text with parameters. This section describes bothways.

DML Statements With Parameters[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// set SQL query for update record
q.SQL.Clear;
q.SQL.Add('UPDATE dept SET dname = :dname, loc = :loc WHERE deptno = :de// set parameters
q.ParamByName('deptno').AsInteger := 10;
q.ParamByName('dname').AsString := 'RESEARCH';
q.ParamByName('loc').AsString := 'LOS ANGELES';// execute query
q.Execute;finallyq.Free;end;
end;[C++Builder]{

TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// set SQL query for update record
q->SQL->Clear();q->SQL->Add("UPDATE dept SET dname = :dname, loc = :loc WHERE deptno = :// set parameters
q->ParamByName("deptno")->AsInteger = 10;
q->ParamByName("dname")->AsString = "RESEARCH";
q->ParamByName("loc")->AsString = "LOS ANGELES";// execute queryq->Execute();}__finally{q->Free();© 2019 Devart

82

SQL Server Data Access Components}}

DML Statements As Plain Text
[Delphi]varq: TMSQuery;
begin
q := TMSQuery.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
q.Connection := con;// set SQL query for update record
q.SQL.Clear;
q.SQL.Add('UPDATE dept SET dname = ''RESEARCH'', loc = ''LOS ANGELES'' W// execute query
q.Execute;finallyq.Free;end;
end;[C++Builder]{

TMSQuery* q = new TMSQuery(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
q->Connection = con;// set SQL query for update record
q->SQL->Clear();q->SQL->Add("UPDATE dept SET dname = 'RESEARCH', loc = 'LOS ANGELES' WHE// execute queryq->Execute();}__finally{q->Free();}}

Additional Information
It is also possible to use stored procedures for modifying data. In this case, all data
manipulation logic is defined on server. You can find more about using stored procedures inthe tutorial "Stored Procedures".

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartGetting Started

3.12

83

Stored ProceduresThis tutorial describes how to insert data into tables using the components. This tutorialdescribes how to work with stored procedures using the TMSStoredProc component.
1. Requirements
2. General information
3. Input parameters
4. Output parameters
5. Input/output parameters
6. Return values
7. Returning result sets

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact"), how to create necessary objects
on the server (tutorial "Creating Database Objects"), and how to insert data to created tables(tutorial "Inserting Data Into Tables").

General information
A stored procedure is a schema object that consists of a set of SQL statements, grouped
together, stored in the database, and run as a unit to solve a specific problem or perform aset of related tasks. Procedures let you combine the ease and flexibility of SQL with theprocedural functionality of a structured programming language. Large or complex processingthat might require execution of several SQL statements is moved into stored procedures, andall applications call the procedures only.
Objects similar to stored procedures are stored functions. Almost everything that is true forprocedures, holds for functions as well. The main difference between these objects is thatfunction has a return value, and procedure has not. Stored procedures and functions may
have input, output, and input/output parameters.

Input parameters
Input parameter is a parameter which value is passed into a stored procedure/function
module. The value of an IN parameter is a constant; it can't be changed or reassigned within
the module.
For example, the following procedure inserts a new row into the table dept:
CREATE PROCEDURE InsertDept@deptno INT,
@dname VARCHAR(14),@loc VARCHAR(13)© 2019 Devart

84

SQL Server Data Access Components

AS
BEGIN
INSERT INTO dept(deptno, dname, loc) VALUES(@deptno, @dname, @loc);
END
It needs to receive the values to be inserted into the new record, and thus the procedure has
three input parameters, corresponding to each field of the table. This procedure may be
executed as follows:
EXECUTE InsertDept 10,'ACCOUNTING','NEW YORK'
To execute the InsertDept stored procedure using the TMSStoredProc component, thefollowing code can be used:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choose a stored procedure name to execute
sp.StoredProcName := 'InsertDept';// build a query for a chosen stored procedure based on the Params and S
sp.PrepareSQL;// assign parameter values
sp.ParamByName('deptno').AsInteger := 10;
sp.ParamByName('dname').AsString := 'ACCOUNTING';
sp.ParamByName('loc').AsString := 'NEW YORK';// execute the stored procedure
sp.Execute;finally
sp.Free;end;
end;[C++Builder]{

TMSStoredProc* sp = new TMSStoredProc(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choose a stored procedure name to executesp->StoredProcName = "InsertDept";// build a query for chosen stored procedure based on the Params and Sto
sp->PrepareSQL();// assign parameter values
sp->ParamByName("deptno")->AsInteger = 10;
sp->ParamByName("dname")->AsString = "ACCOUNTING";
sp->ParamByName("loc")->AsString = "NEW YORK";// execute the stored proceduresp->Execute();}© 2019 DevartGetting Started

85__finally{
sp->Free();}}

Output parameters
Output parameter is a parameter which value is passed out of the stored procedure/function
module. An OUT parameter must be a variable, not a constant. It can be found only on theleft-hand side of an assignment in the module. You cannot assign a default value to an OUT
parameter outside of the module's body. In other words, an OUT parameter behaves like anuninitialized variable.
For example, the following stored procedure returns the count of records in the table dept:
CREATE PROCEDURE CountDept@cnt INT OUT
AS
BEGIN
SELECT @cnt = count(*) FROM dept;
END
Note 1: SQL Server treats output parameters as input/output parameters.
Note 2: SQL Server stored functions do not support output parameters.
To execute the CountDept stored procedure using the TMSStoredProc component, thefollowing code can be used:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choose a stored procedure name to execute
sp.StoredProcName := 'CountDept';// build a query for chosen stored procedure based on the Params and Sto
sp.PrepareSQL;// execute the stored procedure
sp.Execute;// show the value of the output parameter
ShowMessage(IntToStr(sp.ParamByName('cnt').AsInteger));
finally
sp.Free;end;
end;[C++Builder]{
TMSStoredProc* sp = new TMSStoredProc(NULL);© 2019 Devart

86

SQL Server Data Access Componentstry{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choose a stored procedure name to executesp->StoredProcName = "CountDept";// build a query for chosen stored procedure based on the Params and Sto
sp->PrepareSQL();// execute the stored proceduresp->Execute();// show the value of the output parameter
ShowMessage(IntToStr(sp->ParamByName("cnt")->AsInteger));}__finally{
sp->Free();}}

Input/output parameters
An input/output parameter is a parameter that functions as an IN or an OUT parameter orboth. The value of the IN/OUT parameter is passed into the stored procedure/function and a
new value can be assigned to the parameter and passed out of the module. An IN/OUT
parameter must be a variable, not a constant. It can be found on both sides of an assignment.
In other words, an IN/OUT parameter behaves like an initialized variable.
For example, the following stored procedure returns the salary with five percents bonus:
CREATE PROCEDURE GiveBonus@sal FLOAT OUT
AS
BEGIN
SET @sal = @sal * 1.05;
END
Note 1: SQL Server does not have input/output parameters as such. SQL Server treats
output parameters as input/output parameters.
Note 2: SQL Server stored functions do not support input/output parameters.
To execute the GiveBonus stored procedure using the TMSStoredProc component, thefollowing code can be used:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choose a stored procedure name to execute
sp.StoredProcName := 'GiveBonus';© 2019 DevartGetting Started

87// build a query for chosen stored procedure based on the Params and Sto
sp.PrepareSQL;// assign parameter values
sp.ParamByName('sal').AsFloat := 500.5;// execute the stored procedure
sp.Execute;// show the value of the input/output parameter
ShowMessage(FloatToStr(sp.ParamByName('sal').AsFloat));finally
sp.Free;end;
end;[C++Builder]{

TMSStoredProc* sp = new TMSStoredProc(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choose a stored procedure name to executesp->StoredProcName = "GiveBonus";// build a query for chosen stored procedure based on the Params and Sto
sp->PrepareSQL();// assign parameter values
sp->ParamByName("sal")->AsFloat = 500.5;// execute of the stored proceduresp->Execute();// show the value of the input/output parameter
ShowMessage(FloatToStr(sp->ParamByName("sal")->AsFloat));}__finally{
sp->Free();}}

Return values
In SQL Server, both stored procedures and stored functions can return values that indicate
the result of the execution. For example, the GiveBonus stored procedure (that is describedabove) returns a value of 0. Usually, a zero value indicates success and a nonzero value
indicates failure. The following modified version of the GiveBonus stored procedure returns avalue of 1 if the value of the @sal parameter is null or negative, and 0 otherwise:
CREATE PROCEDURE GiveBonus@sal FLOAT OUT
AS
BEGIN
IF (@sal IS NULL) OR (@sal < 0)
RETURN 1;
SET @sal = @sal * 1.05;
RETURN 0;© 2019 Devart

88

SQL Server Data Access Components

END
Note 1: SQL Server stored procedures can return only integer values. When a stored
procedure returns other values, for example, a string value, SQL Server converts it to theinteger value.
Note 2: Stored functions can return values of any type.
To execute the GiveBonus stored procedure using the TMSStoredProc component, thefollowing code can be used:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choosing a stored procedure name to execute
sp.StoredProcName := 'GiveBonus';// building a query for chosen stored procedure based on the Params andsp.PrepareSQL;// assigning parameter values
sp.ParamByName('sal').AsFloat := 500.5;// executing of the stored procedure
sp.Execute;// showing the return value
ShowMessage(IntToStr(sp.ParamByName('return_value').AsInteger));// showing the value of the input/output parameter
ShowMessage(FloatToStr(sp.ParamByName('sal').AsFloat));finally
sp.Free;end;
end;[C++Builder]{
TMSStoredProc* sp = new TMSStoredProc(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choosing a stored procedure name to executesp->StoredProcName = "GiveBonus";// building a query for chosen stored procedure based on the Params and
sp->PrepareSQL();// assigning parameter values
sp->ParamByName("sal")->AsFloat = 500.5;// executing of the stored proceduresp->Execute();// showing the return value
ShowMessage(IntToStr(sp->ParamByName("return_value")->AsInteger));// showing the value of the input/output parameter
ShowMessage(FloatToStr(sp->ParamByName("sal")->AsFloat));}© 2019 DevartGetting Started

89__finally{
sp->Free();}}
The same task can be resolved by using stored functions as well. For example, the following
stored functions returns a value of 0 if the value of the @sal parameter is null or negative, andthe correct bonus otherwise:
CREATE FUNCTION GiveBonus(@sal FLOAT)RETURNS FLOATAS
BEGIN
IF (@sal IS NULL) OR (@sal < 0)
RETURN 0;
RETURN @sal * 1.05;
END
As is was mentioned previously, SQL Server stored functions do not support output and input/
output parameters. That is why the behaviour of the GiveBonus stored function is slightly
different from the behaviour of the GiveBonus stored procedure.
To execute the GiveBonus stored function using the TMSStoredProc component, thefollowing code can be used:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choosing a stored function name to execute
sp.StoredProcName := 'GiveBonus';// building a query for chosen stored function based on the Params and S
sp.PrepareSQL;// assigning parameter values
sp.ParamByName('sal').AsFloat := 500.5;// executing of the stored function
sp.Execute;// showing the return value
ShowMessage(FloatToStr(sp.ParamByName('return_value').AsFloat));finally
sp.Free;end;
end;[C++Builder]{
TMSStoredProc* sp = new TMSStoredProc(NULL);
try© 2019 Devart

90

SQL Server Data Access Components{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choosing a stored function name to executesp->StoredProcName = "GiveBonus";// building a query for chosen stored function based on the Params and S
sp->PrepareSQL();// assigning parameter values
sp->ParamByName("sal")->AsFloat = 500.5;// executing of the stored function
sp->Execute();// showing the return value
ShowMessage(FloatToStr(sp->ParamByName("return_value")->AsFloat));}__finally{
sp->Free();}}

Returning result sets
Besides scalar variables, a stored procedure can return result sets, i.e. the results of a
SELECT statement. This question is discussed in details in the tutorial "Working With Result
Sets Using Stored Procedures".

© 1997-2019
Devart. All Rights
Reserved.

3.13

Request Support

DAC Forum

Provide Feedback

Working With Result Sets Using Stored ProceduresThis tutorial describes how to retrieve and modify result sets obtained from stored procedures
using the TMSStoredProc component.

Requirements
This walkthrough supposes that you know how to connect to server (tutorials "Connecting To
SQL Server" and "Connecting To SQL Server Compact"), how to create necessary objects
on the server (tutorial "Creating Database Objects"), and how to insert data to created tables(tutorial "Inserting Data Into Tables").

General information
Besides scalar variables, stored procedures can return result sets, i.e. the results of SELECT
statements. Data can be inserted or modified in obtained result sets using the dataset
functionality of the TMSStoredProc component.
The goal of this tutorial is to retrieve and modify data from the dept table using the© 2019 DevartGetting Started

91

TMSStoredProc component. The following stored procedure will be used to retrieve data:
CREATE PROCEDURE SelectDept
AS
BEGIN
SELECT * FROM dept;
END

Using DataSet functionality
The Insert, Append, Edit, and Post methods of the TMSStoredProc component can be used
to insert and modify data in obtained result sets. DML statements are generated by
TMSStoredProc internally. The code below demonstrates using these methods:[Delphi]var
sp: TMSStoredProc;
begin
sp := TMSStoredProc.Create(nil);try// con is either TMSConnection or TMSCompactConnection already set up
sp.Connection := con;// choose a stored procedure namesp.StoredProcName := 'SelectDept';// build a query for a chosen stored procedure based on the Params and S
sp.PrepareSQL;// retrieve data
sp.Open;// append record
sp.Append;
sp.FieldByName('deptno').AsInteger := 50;
sp.FieldByName('dname').AsString := 'SALES';
sp.FieldByName('loc').AsString := 'NEW YORK';
sp.Post;// insert record
sp.Insert;
sp.FieldByName('deptno').AsInteger := 60;
sp.FieldByName('dname').AsString := 'ACCOUNTING';
sp.FieldByName('loc').AsString := 'LOS ANGELES';
sp.Post;// to make the record with deptno=10 the current record
sp.FindKey([10]);// modify record
sp.Edit;sp.FieldByName('dname').AsString := 'RESEARCH';
sp.FieldByName('loc').AsString := 'LOS ANGELES';
sp.Post;
finally
sp.Free;end;
end;[C++Builder]{© 2019 Devart

92

SQL Server Data Access Components

TMSStoredProc* sp = new TMSStoredProc(NULL);try{// con is either TMSConnection or TMSCompactConnection already set up
sp->Connection = con;// choose a stored procedure namesp->StoredProcName = "SelectDept";// build a query for a chosen stored procedure based on the Params and S
sp->PrepareSQL();// retrieve data
sp->Open();// append record
sp->Append();
sp->FieldByName("deptno")->AsInteger = 50;
sp->FieldByName("dname")->AsString = "SALES";
sp->FieldByName("loc")->AsString = "NEW YORK";
sp->Post();// insert record
sp->Insert();sp->FieldByName("deptno")->AsInteger = 60;
sp->FieldByName("dname")->AsString = "ACCOUNTING";
sp->FieldByName("loc")->AsString = "LOS ANGELES";
sp->Post();// to make the record with deptno=10 the current record
sp->FindKey(ARRAYOFCONST((10)));// modify record
sp->Edit();
sp->FieldByName("dname")->AsString = "RESEARCH";
sp->FieldByName("loc")->AsString = "LOS ANGELES";
sp->Post();}__finally{
sp->Free();}}© 1997-2019
Devart. All Rights
Reserved.

3.14

Request Support

DAC Forum

Provide Feedback

Demo Projects
SDAC includes a number of demo projects that show off the main SDAC functionality anddevelopment patterns.
The SDAC demo projects consist of one large project called SdacDemo with demos for all
main SDAC components, use cases, and data access technologies, and a number ofsmaller projects on how to use SDAC in different IDEs and how to integrate SDAC with thirdparty components.
Most demo projects are built for Delphi and Borland Developer Studio. There are only two
SDAC demos for C++Builder. However, the C++Builder distribution includes source code forall other demo projects as well.

© 2019 DevartGetting Started

93

Where are the SDAC demo projects located?
In most cases all SDAC demo projects are located in "%Sdac%\Demos\".
In Delphi 2007 for Win32 under Windows Vista all SDAC demo projects are located in "My
Documents\Devart\Sdac for Delphi 2007\Demos", for example "C:\Documents and Settings\All Users\Documents\Devart\Sdac for Delphi 2007\Demos\".
The structure of the demo project directory depends on the IDE version you are using.
For most new IDEs the structure will be as follows.
Demos|—SdacDemo [The main SDAC demo project]|—TechnologySpecific||— MSSQLCompact [Win32 version of the demo, using SQL Server

Compact Edition]|—ThirdParty||— [A collection of demo projects on integration with third-

party components]|—Performance [Demo project, that compares performance of SDAC
with another components (BDE, ADO, dbExpress)]|—Miscellaneous|— [Some other demo projects on design technologies]
SdacDemo is the main demo project that shows off all the SDAC functionality. The otherdirectories contain a number of supplementary demo projects that describe special use
cases. A list of all the samples in the SDAC demo project and a description for the
supplementary projects is provided in the following section.
Note: This documentation describes ALL the SDAC demo projects. The actual demo
projects you will have installed on your computer depends on your SDAC version, SDAC
edition, and the IDE version you are using. The integration demos may require installation of
third-party components to compile and work properly.

Instructions for using the SDAC demo projects
To explore an SDAC demo project,
1. Launch your IDE.
2. In your IDE, choose File|Open Project from the menu bar.
3. Find the directory you installed SDAC to and open the Demos folder.
4. Browse through the demo project folders located here and open the project file of the demo
© 2019 Devart

94

SQL Server Data Access Components

you would like to use.
5. Compile and launch the demo. If it exists, consult the ReadMe file for more details.
The included sample applications are fully functional. To use the demos, you have to first set
up a connection to SQL Server. You can do so by clicking on the "Connect" button.
Many demos may also use some database objects. If so, they will have two object
manipulation buttons, "Create" and "Drop". If your demo requires additional objects, click"Create" to create the necessary database objects. When you are done with a demo, click"Drop" to remove all the objects used for the demo from your database.
Note: The SDAC demo directory includes two sample SQL scripts for creating and dropping
all the test schema objects used in the SDAC demos. You can modify and execute this script
manually, if you would like. This will not change the behavior of the demos.
You can find a complete walkthrough for the main SDAC demo project in the Getting Started
section. The other SDAC demo projects include a ReadMe file with individual building andlaunching instructions.

Demo project descriptions
SdacDemo
SdacDemois one large project that includes three collections of demos.
Working with components
A collection of samples that show how to work with the basic SDAC components.
General demos
A collection of samples that show off the SDAC technology and demonstrate some ways
to work with data.
SQL Server-specific demos
A collection of samples that demonstrate how to incorporate SQL Server features indatabase applications.
SdacDemo can be opened from %Sdac%\Demos\SdacDemo\SdacDemo.dpr (.bdsproj). The
following table describes all the demos contained in this project.

Working with Components
Name

Description

This demo uses the TMSChangeNotification component to automate
ChangeNotifica synchronization of local data with the actual data on the server.
tion
Synchronization happens immediately after changes are applied to© 2019 DevartGetting Started

95

the server from a different connection.
Demonstrates how to customize the SDAC connect dialog . Changes
the standard SDAC connect dialog to two custom connect dialogs.
ConnectDialog The first customized sample dialog is inherited from the TForm class,and the second one is inherited from the default SDAC connect
dialog class.
Demonstrates how to work with the TCRDBGrid component. Shows
CRDBGrid
off the main TCRDBGrid features, like filtering, searching, stretching,using compound headers, and more.
Demonstrates how to backup data from tables with the TMSDumpcomponent. Shows how to use scripts created during back up to
Dump
restore table data. This demo lets you back up a table either byspecifying the table name or by writing a SELECT query.
Uses the TMSLoader component to quickly load data into a server
Loadertable. This demo also compares the two TMSLoader data loading
handlers: GetColumnData and PutData .
Demonstrates working with TMSQuery , which is one of the mostuseful SDAC components. Includes many TMSQuery usage
scenarios. Demonstrates how to execute queries in both standard
Query
and NonBlocking mode and how to edit data and export it to XML
files.
Note: This is a very good introductory demo. We recommend starting
here when first becoming familiar with SDAC.
ServiceBroker Demonstrates working with the TMSServiceBroker component. This
sample shows how to organize simple messaging.
Uses the TMSSQL component to execute SQL statements.
Sql
Demonstrates how to work in a separate thread, in standard mode, in
NonBlocking mode, and how to break long-duration query execution.
Uses the TMSStoredProc component to access an editable
StoredProc
recordset from an SQL Server stored procedure in the client
application.
Demonstrates how to use TMSTable to work with data from a single
table on the server without writing any SQL queries manually.
Table
Performs server-side data sorting and filtering and retrieves results
for browsing and editing.
Demonstrates usage of the TMSTransaction component to control
Transaction
distributed transactions. The demo shows how to ensure consistent
data changes across two connections.
Demonstrates using the TMSUpdateSQL component to customize
UpdateSQL
update commands. Lets you optionally use TMSSQL and TMSQueryobjects for carrying out insert, delete, query, and update commands.
VirtualTable© 2019 Devart

Demonstrates working with the TVirtualTable component. This
sample shows how to fill virtual dataset with data from other datasets,
filter data by a given criteria, locate specified records, perform file

96

SQL Server Data Access Components

operations, and change data and table structure.

General Demos
Name

Description
Demonstrates how to perform the most important tasks of working
CachedUpdate with data in CachedUpdates mode, including highlightingsuncommitted changes, managing transactions, and committingchanges in a batch.
Demonstrates SDAC's local storage functionality. This sample shows
FilterAndIndex how to perform local filtering, sorting and TVirtualTable by multiple
fields, including by calculated and lookup fields.
Uses SDAC functionality to work with master/detail relationships. This
sample shows how to use TMSMetaData local master/detail
MasterDetailfunctionality. Demonstrates different kinds of master/detail linking,including linking by SQL, by simple fields, and by calculated fields.
Uses SDAC functionality to work with BLOB fields and graphics.. The
sample demonstrates how to retrieve binary data from SQL Server
Picturesdatabase and display it on visual components. Sample also shows
how to load and save pictures to files and to the database.
Demonstrates updating a recordset using stored procedures. Update
StoredProcUp events are tied to stored procedure calls in design time, and every
recordset change causes the corresponding stored procedure call todates
be performed. The commands to call stored procedures are stored in
the SQLInsert , SQLDelete , SQLUpdate properties of TMSQuery .
Demonstrates how SDAC can be used in multithreaded applications.
Threads
This sample allows you to set up several threads and test SDAC's
performance with multithreading.

SQL Server-specific Demos
Name

Description
This demo shows how to ensure database consistency with locking
mechanism of SQL Server through the SDAC functionality. Basing on
Lockyour choice, a record can be locked exclusively, or just protected fromwriting.
Demonstrates SDAC functionality for working with long string fields
LongStrings(fields that have more than 256 characters). Shows the different ways
they can be displayed as memo fields and string fields.
Compares performance of opening a large recordset with different
ServerCursors cursor types : client cursor in FetchAll =True mode, client cursor in
FetchAll =False mode, and server cursor.

© 2019 DevartGetting Started

Text

UDT

97

Uses SDAC functionality to work with text. The sample demonstrates
how to retrieve text data from SQL Server database and display it on
visual components. Sample also shows how to load and save text tofiles and to the database.
This demo demonstrates SDAC abilities for working with CLR Userdefined Types (UDT) of SQL Server. The demo folder includes thedemo itself, and the sources of a sample type used in this demo. For
more information on how to perform all necessary settings, see theReadme.html file in the demo folder.

Supplementary Demo Projects
SDAC also includes a number of additional demo projects that describe some special use
cases, show how to use SDAC in different IDEs and give examples of how to integrate it withthird-party components. These supplementary SDAC demo projects are sorted into
subfolders in the %Sdac%\Demos\ directory.

Location

ThirdParty© 2019 Devart

Name

Description
Demonstrates how SDAC can beused with FastReport components.
This project consists of two parts.
The first part is several packages
FastReport that integrate SDAC components
into the FastReport editor. The
second part is a demo applicationthat lets you design and preview
reports with SDAC technology in the
FastReport editor.
Uses InfoPower components todisplay recordsets retrieved with
SDAC. This demo project displays
InfoPower an InfoPower grid component andfills it with the result of an SDAC
query. Shows how to link SDAC data
sources to InfoPower components.
A collection of sample projects thatshow how to use SDAC components
as data sources for IntraWeb
applications. Contains IntraWeb
IntraWeb samples for setting up a connection,
querying a database and modifying
data and working with
CachedUpdates and MasterDetail
relationships.

98

SQL Server Data Access Components

TechnologySpecificMiscellaneousLets you launch and view a
QuickRepo QuickReport application based on
SDAC. This demo project lets yourt
modify the application in designtime.
Uses SDAC data sources to createa ReportBuilder report that takes
data from SQL Server database.
ReportBuil Shows how to set up a
ReportBuilder document in designder
time and how to integrate SDAC
components into the Report Builder
editor to perform document design inrun-time.
Demonstrates how to create
applications that work with Microsoft
SQL Server Compact Edition. Democonnects to a database and opens a
MSSQLCo table. If the specified database does
mpact
not exists, it will be createdautomatically. User must have SQL
Server Compact Edition installed totest this demo. This is the Win32
version of the project.
A general demo project about
creating SDAC-based applications
CBuilder with C++Builder. Lets you execute
SQL scripts and work with result sets
in a grid. This is one of the two
SDAC demos for C++Builder.
Demonstrates creating and loading
DLLs for SDAC-based projects.
This demo project consists of twoparts - an MSDll project that createsa DLL of a form that sends a queryto the server and displays its results,
Dll
and an MSExe project that can be
executed to display a form forloading and running this DLL. Allows
you to build a dll for one SDACbased project and load and test it
from a separate application.
FailOver

Demonstrates the recommended
approach to working with unstablenetworks. This sample lets you© 2019 DevartGetting Started

SdacDemo© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

99

perform transactions and updates inseveral different modes, simulate asudden session termination, andview what happens to your data state
when connections to the server are
unexpectedly lost. Shows off
CachedUpdates, LocalMasterDetail,
FetchAll, Pooling, and different
Failover modes.
Demonstrates using MIDAS
technology with SDAC. This project
consists of two parts: a MIDAS
server that processes requests tothe database and a thin MIDAS
Midasclient that displays an interactive
grid. This demo shows how to build
thin clients that display interactive
components and delegate all
database interaction to a server
application for processing.
Measures SDAC performance on
several types of queries. This project
lets you compare SDAC
Performan performance to BDE, ADO, andce
dbExpress. Tests the following
functionality: Fetch, Master/Detail,Stored Procedure Call, Multi
Executing, and Insert/Post.
Demonstrates working with the
TVirtualTable component. This
sample shows how to fill virtual
dataset with data from other
VirtualTabl datasets, filter data by a given
eCB
criteria, locate specified records,
perform file operations, and change
data and table structure. This is oneof the two demo projects for C++BuilderSdacDemo [Win32 version of the main SDAC
demo project - see above]
Request Support

DAC Forum

Provide Feedback

100

3.15

SQL Server Data Access Components

Deployment
SDAC requires OLE DB to be installed on the workstation. In current versions of Microsoft
Windows, as Windows 2000, OLE DB is already included as standard package. But it ishighly recommended to download the latest version (newer than 2.5) of Microsoft Data
Access Components (MDAC).
Many features of SQL Server like Query Notifications, MARS require Microsoft SQL Server
Native Client. If you need to use these features, you should download and install Microsoft
SQL Server Native Client.
For applications that use SQL Server Compact Edition, the server itself is required to beinstalled on the client computer.
In order to use extended abilities of UDT fields , you will need to deploy theDevart.Sdac.UDTProxy.dll file with your application. This file should be present in the directorywith your application, or registered in GAC.
SDAC applications can be built and deployed with or without run-time libraries. Using run-time
libraries is managed with the "Build with runtime packages" check box in the Project Options
dialog box.

Deploying Windows applications built without run-time
packages
You can check that your application does not require run-time packages by making sure the"Build with runtime packages" check box is not selected in the Project Options dialog box.

Trial Limitation Warning
If you are evaluating deploying Windows applications with SDAC Trial Edition, you will need to
deploy the following BPL files:

dacXX.bpl
sdacXX.bpl

alwaysalwaysand their dependencies (required IDE BPL files) with your application, even if it is built without
run-time packages:

rtlXX.bpl
dbrtlXX.bpl
vcldbXXX.bpl

alwaysalwaysalways

Deploying Windows applications built with run-time
packages© 2019 DevartGetting Started

101

You can set your application to be built with run-time packages by selecting the "Build withruntime packages" check box in the Project Options dialog box before compiling yourapplication.
In this case, you will also need to deploy the following BPL files with your Windows
application:

dacXX.bpl
alwayssdacXX.bpl
alwaysdacvclXX.bpl
if your application uses the SdacVcl unit
sdacvclXX.bpl if your application uses the SdacVcl unit
crcontrolsXX.bpl if your application uses the CRDBGrid component© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.

4

Using SDAC
This section describes basics of using SQL Server Data Access Components
Connecting in Direct Mode
Updating Data with SDAC Dataset Components
Master/Detail Relationships
Using Table-Valued Parameters
Data Type Mapping
Data Encryption
Working in an Unstable Network
Disconnected Mode
Performance of Obtaining Data
Increasing Performance
MacrosDataSet Manager
SQL Server Compact Edition
Working with User Defined Types (UDT)
TMSTransaction Component
DBMonitor
Writing GUI Applications with SDAC
Connection Pooling
Compatibility with Previous Versions© 2019 Devart

102

SQL Server Data Access Components

64-bit Development with Embarcadero RAD Studio XE2
Database Specific Aspects of 64-bit Development
FILESTREAM Data
Demo Projects
Deployment© 1997-2019
Devart. All Rights
Reserved.

4.1

Request Support

DAC Forum

Provide Feedback

Connecting in Direct ModeSDAC Professional Edition allows to connect to SQL Server in two ways: using the OLE DB
interface or in the Direct mode via TCP/IP. The chosen connection mode is regulated by the
TMSConnection.Options.Provider property.

SDAC connection modes
By default, SDAC, like most applications that work with SQL Server, uses the OLE DB
interface directly through a set of COM-based interfaces to connect to server. Such approachallows using client applications on Windows workstations only.
To overcome these problems, SDAC Professional Edition includes an option to connect to
SQL Server directly over the network using the TCP/IP protocol. This is referred to asconnecting in the Direct mode. Connection in the Direct mode does not require OLEDB
provider or SQL Native Client provider to be installed on target machines. The only
requirement for running an SDAC-based application that uses the Direct mode is that theoperating system must support the TCP/IP protocol.

Setting up Direct mode connections
Here is an example that illustrates connecting to SQL Server in the Direct mode. The server's
IP address is 205.227.44.44, its port number is 1433 (this is the most commonly used port for
SQL Server).
var
MSConnection: TMSConnection;. . .
MSConnection.Options.Provider := prDirect;
MSConnection.Authentication := auServer;
MSConnection.Username := 'sa';
MSConnection.Password := '';MSConnection.Server := '205.227.44.44';
MSConnection.Port := 1433;
MSConnection.Connect;
All we have to do is to set the TMSConnection.Options.Provider property to prDirect to enable© 2019 Devart

Using SDAC

103

Direct mode connections in your application. You do not have to rewrite other parts of yourcode.

Comparison of Client mode vs. Direct mode
Applications that use the OLE DB interface and those that use the Direct mode have similar
size and performance. Security when using the Direct mode is the same as using the OLE
DB interface.

Advantages of using the Direct mode
Installation of OLEDB providers or SQL Native Client provider is not required.
System requirements are reduced.
Support for SQL Server in Mac OS X application development.

Direct mode limitations
Connection using TCP/IP protocol only
Certain problems may occur when using firewalls.

© 1997-2019
Devart. All Rights
Reserved.

4.2

Request Support

DAC Forum

Provide Feedback

Updating Data with SDAC Dataset Components
SDAC components that are descendants from TCustomDADataSet provide different means
for reflecting local changes to the server.
The first approach is to use automatic generation of update SQL statements. Using thisapproach you should provide a SELECT statement, everything else will be made by SDAC
automatically. In case when a SELECT statement uses multiple tables, you can use
UpdatingTable property to specify which table will be updated. If UpdatingTable is blank, thetable that corresponds to the first field in the dataset is used. This approach is the most
preferable and is used in most cases.
Another approach is to set update SQL statements using SQLInsert, SQLUpdate and
SQLDelete properties. Set them with SQL statements that will perform corresponding data
modifications on behalf of the original statement whenever insert, update or delete operation
is called. This is useful when there is no possibility to generate correct statement or you needto execute some specific statements. For example update operations should be made withstored procedure calls.
You may also assign UpdateObject property with the TMSUpdateSQL class instance whichholds all updating SQL statements in one place. You can generate all these SQL statements
using SDAC design time editors. For more careful customization of data update operations© 2019 Devart

104

SQL Server Data Access Components

you can use InsertObject, ModifyObject and DeleteObject properties of TMSUpdateSQL
component.

See Also
TMSQuery
TMSStoredProc
TMSTable
TMSUpdateSQL© 1997-2019
Devart. All Rights
Reserved.

4.3

Request Support

DAC Forum

Provide Feedback

Master/Detail Relationships
Master/detail (MD) relationship between two tables is a very widespread one. So it is very
important to provide an easy way for database application developer to work with it. Lets
examine how SDAC implements this feature.
Suppose we have classic MD relationship between "Department" and "Employee" tables.
"Department" table has field Dept_No. Dept_No is a primary key.
"Employee" table has a primary key EmpNo and foreign key Dept_No that binds "Employee"
to "Department".
It is necessary to display and edit these tables.
SDAC provides two ways to bind tables. First code example shows how to bind two
TCustomMSDataSet components (TMSQuery, TMSTable or even TMSStoredProc) into MD
relationship via parameters.
procedure TForm1.Form1Create(Sender: TObject);var
Master, Detail: TMSQuery;
MasterSource: TDataSource;
begin// create master dataset
Master := TMSQuery.Create(Self);
Master.SQL.Text := 'SELECT * FROM Department';// create detail dataset
Detail := TMSQuery.Create(Self);
Detail.SQL.Text := 'SELECT * FROM Employee WHERE Dept_No = :Dept_No';// connect detail dataset with master via TDataSource component
MasterSource := TDataSource.Create(Self);
MasterSource.DataSet := Master;
Detail.MasterSource := MasterSource;// open master dataset and only then detail dataset
Master.Open;
Detail.Open;end;
Pay attention to one thing: parameter name in detail dataset SQL must be equal to the field© 2019 Devart

Using SDAC

105

name or the alias in the master dataset that is used as foreign key for detail table. After
opening detail dataset always holds records with Dept_No field value equal to the one in thecurrent master dataset record.
There is an additional feature: when inserting new records to detail dataset it automatically fills
foreign key fields with values taken from master dataset.
Now suppose that detail table "Department" foreign key field is named DepLink but not
Dept_No. In such case detail dataset described in above code example will not autofill
DepLink field with current "Department".Dept_No value on insert. This issue is solved insecond code example.
procedure TForm1.Form1Create(Sender: TObject);var
Master, Detail: TMSQuery;
MasterSource: TDataSource;
begin// create master dataset
Master := TMSQuery.Create(Self);
Master.SQL.Text := 'SELECT * FROM Department';// create detail dataset
Detail := TMSQuery.Create(Self);
Detail.SQL.Text := 'SELECT * FROM Employee';// setup MD
Detail.MasterFields := 'Dept_No';// primary key in Department
Detail.DetailFields := 'DepLink'; // foreign key in Employee// connect detail dataset with master via TDataSource component
MasterSource := TDataSource.Create(Self);
MasterSource.DataSet := Master;
Detail.MasterSource := MasterSource;// open master dataset and only then detail dataset
Master.Open;
Detail.Open;end;
In this code example MD relationship is set up using MasterFields and DetailFields properties.
Also note that there are no WHERE clause in detail dataset SQL.
To defer refreshing of detail dataset while master dataset navigation you can use DetailDelay
option.
Such MD relationship can be local and remote, depending on the
TCustomDADataSet.Options.LocalMasterDetail option. If this option is set to True, dataset
uses local filtering for establishing master-detail relationship and does not refer to the server.
Otherwise detail dataset performs query each time when record is selected in masterdataset. Using local MD relationship can reduce server calls number and save server
resources. It can be useful for slow connection. CachedUpdates mode can be used for detaildataset only for local MD relationship. Using local MD relationship is not recommended when
detail table contains too many rows, because in remote MD relationship only records that
correspond to the current record in master dataset are fetched. So, this can decrease© 2019 Devart

106

SQL Server Data Access Components

network traffic in some cases.

See Also
TCustomDADataSet.Options
TMemDataSet.CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

4.4

Request Support

DAC Forum

Provide Feedback

Using Table-Valued Parameters
Table-valued parameters are a new parameter type introduced in SQL Server 2008. They canbe used to send multiple rows of data to a Transact-SQL statement or a stored routine
without creating a temporary table or many parameters. To learn more on table-valued
parameters, see http://msdn.microsoft.com/en-us/library/bb510489.aspx
This topic demonstrates how to use table-valued parameters in your application by the help of
SDAC
1. In order to pass a table as a parameter to a stored procedure or function, create a TABLE
TYPE as follows:
CREATE TYPE DeptTableType AS TABLE(DNAME VARCHAR(20),
LOC VARCHAR(20))
2. In a stored procedure we will transfer data from a parameter to a table on a server. Here isa script example for creating a table:
CREATE TABLE DEPT(
DEPTNO INT IDENTITY(1,1) NOT NULL PRIMARY KEY,DNAME VARCHAR(20) NULL,LOC VARCHAR(20) NULL)
3. Create a stored procedure that uses the table type:
CREATE PROCEDURE SP_InsertDept@TVP DeptTableType READONLYAS
BEGIN
INSERT INTO DEPT ([DNAME], [LOC])
SELECT * FROM @TVP
END
4. To work with Table-Valued Parameters, you should use the TMSTableData component. Fillit with data:© 2019 Devart

Using SDAC

107

MSTableData.TableTypeName := 'DeptTableType';
MSTableData.Open;MSTableData.Append;
MSTableData.Fields[0].AsString := 'ACCOUNTING';
MSTableData.Fields[1].AsString := 'NEW YORK';
MSTableData.Post;
MSTableData.Append;
MSTableData.Fields[0].AsString := 'RESEARCH';
MSTableData.Fields[1].AsString := 'DALLAS';
MSTableData.Post;
MSTableData.Append;
MSTableData.Fields[0].AsString := 'SALES';MSTableData.Fields[1].AsString := 'CHICAGO';
MSTableData.Post;
MSTableData.Append;
MSTableData.Fields[0].AsString := 'OPERATIONS';MSTableData.Fields[1].AsString := 'BOSTON';
MSTableData.Post;
5. Use the TMSStoredProc component to transfer data from the TMSTableData component toa table on a server:
MSStoredProc.StoredProcName := 'SP_InsertDept';
MSStoredProc.PrepareSQL;
MSStoredProc.ParamByName('TVP').AsTable := MSTableData.Table;
MSStoredProc.ExecProc;
MSTableData.Close;© 1997-2019
Devart. All Rights
Reserved.

4.5

Request Support

DAC Forum

Provide Feedback

Data Type Mapping

Overview
Data Type Mapping is a flexible and easily customizable gear, which allows mapping
between DB types and Delphi field types.
In this article there are several examples, which can be used when working with all supported
DBs. In order to clearly display the universality of the Data Type Mapping gear, a separate DB
will be used for each example.

Data Type Mapping Rules
In versions where Data Type Mapping was not supported, SDAC automatically set© 2019 Devart

108

SQL Server Data Access Components

correspondence between the DB data types and Delphi field types. In versions with Data
Type Mapping support the correspondence between the DB data types and Delphi field types
can be set manually.
Here is the example with the numeric type in the following table of a SQL Server database:
CREATE TABLE DECIMAL_TYPES(
ID int IDENTITY (1,1) NOT NULL PRIMARY KEY,
VALUE1 decimal(4, 0),
VALUE2 decimal(10, 0),
VALUE3 decimal(15, 0),
VALUE4 decimal(5, 2),
VALUE5 decimal(10, 4),
VALUE6 decimal(15, 6))
And Data Type Mapping should be used so that:the numeric fields with Scale=0 in Delphi would be mapped to one of the field types:
TSmallintField, TIntegerField or TlargeintField, depending on Precision
to save precision, the numeric fields with Precision>=10 and Scalе<= 4 would be mapped
to TBCDField
and the numeric fields with Scalе>= 5 would be mapped to TFMTBCDField.
The above in the form of a table:

SQL Server data type

Default Delphi field typedecimal(4,0)
decimal(10,0)
decimal(15,0)
decimal(5,2)
decimal(10,4)
decimal(15,6)

ftFloatftFloatftFloatftFloatftFloatftFloatDestination Delphi field
type
ftSmallint
ftInteger
ftLargeint
ftFloat
ftBCD
ftFMTBCD

To specify that numeric fields with Precision <= 4 and Scale = 0 must be mapped toftSmallint, such a rule should be set:var
DBType: Word;
MinPrecision: Integer;
MaxPrecision: Integer;
MinScale: Integer;
MaxScale: Integer;
FieldType: TFieldType;begin
DBType:= msDecimal;
MinPrecision := 0;© 2019 Devart

Using SDAC

109

MaxPrecision := 4;
MinScale:= 0;
MaxScale:= 0;
FieldType:= ftSmallint;
MSConnection.DataTypeMap.AddDBTypeRule(DBType, MinPrecision, MaxPrecision,
end;This is an example of the detailed rule setting, and it is made for maximum visualization.
Usually, rules are set much shorter, e.g. as follows:// clear existing rules
MSConnection.DataTypeMap.Clear;// rule for decimal(4,0)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0,4, 0,0, ftSma// rule for decimal(10,0)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 5,10, 0,
0, ftInt// rule for decimal(15,0)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 11, rlAny, 0,
0, ftLar// rule for decimal(5,2)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0,9, 1, rlAny, ftFlo// rule for decimal(10,4)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 10, rlAny, 1,
4, ftBCD// rule for decimal(15,6)
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 10, rlAny, 5, rlAny, ftFMTRules order
When setting rules, there can occur a situation when two or more rules that contradict toeach other are set for one type in the database. In this case, only one rule will be applied —the one, which was set first.
For example, there is a table in an SQL Server database:
CREATE TABLE DECIMAL_TYPES(
ID int IDENTITY (1,1) NOT NULL PRIMARY KEY,
VALUE1 decimal(5, 2),
VALUE2 decimal(10, 4),
VALUE3 decimal(15, 6))
TBCDField should be used for NUMBER(10,4), and TFMTBCDField - for NUMBER(15,6)
instead of default fields:

SQL Server data typedecimal(5,2)
decimal(10,4)
decimal(15,6)

Default Delphi field typeftFloatftFloatftFloatIf rules are set in the following way:
MSConnection.DataTypeMap.Clear;© 2019 Devart

Destination field typeftFloat
ftBCD
ftFMTBCD

110

SQL Server Data Access Components

MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0,9, rlAny, rlAny, ft
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0, rlAny,
0,
4, ft
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0, rlAny,0, rlAny, ft
it will lead to the following result:

SQL Server data typedecimal(5,2)
decimal(10,4)
decimal(15,6)

Delphi field typeftFloat
ftBCD
ftFMTBCD

But if rules are set in the following way:

MSConnection.DataTypeMap.Clear;
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0, rlAny,0, rlAny, ft
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0, rlAny,
0,
4, ft
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0,9, rlAny, rlAny, ft

SQL Server data typedecimal(5,2)
decimal(10,4)
decimal(15,6)

Delphi field typeftFMTBCD
ftFMTBCD
ftFMTBCDThis happens because the rule
MSConnection.DataTypeMap.AddDBTypeRule(msDecimal, 0, rlAny,0, rlAny, ft

will be applied for the NUMBER fields, whose Precision is from 0 to infinity, and Scale is from0 to infinity too. This condition is met by all NUMBER fields with any Precision and Scale.
When using Data Type Mapping, first matching rule is searched for each type, and it is used
for mapping. In the second example, the first set rule appears to be the first matching rule forall three types, and therefore the ftFMTBCD type will be used for all fields in Delphi.
If to go back to the first example, the first matching rule for the NUMBER(5,2) type is the firstrule, for NUMBER(10,4) - the second rule, and for NUMBER(15,6) - the third rule. So in thefirst example, the expected result was obtained.
So it should be remembered that if rules for Data Type Mapping are set so that two or morerules that contradict to each other are set for one type in the database, the rules will beapplied in the specifed order.

Defining rules for Connection and Dataset
Data Type Mapping allows setting rules for the whole connection as well as for each DataSetin the application.
© 2019 Devart

Using SDAC111

For example, such table is created in SQL Server:
CREATE TABLE PERSON(
ID int IDENTITY (1,1) NOT NULL PRIMARY KEY,
FIRSTNAME varchar(20),LASTNAME varchar(30),
GENDER_CODE varchar(1),BIRTH_DTTM datetime)
It is exactly known that the birth_dttm field contains birth day, and this field should be ftDate in
Delphi, and not ftDateTime. If such rule is set:
MSConnection.DataTypeMap.Clear;
MSConnection.DataTypeMap.AddDBTypeRule(msDateTime, ftDate);
all DATETIME fields in Delphi will have the ftDate type, that is incorrect. The ftDate type was
expected to be used for the DATETIME type only when working with the person table. In thiscase, Data Type Mapping should be set not for the whole connection, but for a particular
DataSet:
MSQuery.DataTypeMap.Clear;
MSQuery.DataTypeMap.AddDBTypeRule(msDateTime, ftDate);
Or the opposite case. For example, DATETIME is used in the application only for datestorage, and only one table stores both date and time. In this case, the following rules setting
will be correct:
MSConnection.DataTypeMap.Clear;
MSConnection.DataTypeMap.AddDBTypeRule(msDateTime, ftDate);
MSQuery.DataTypeMap.Clear;
MSQuery.DataTypeMap.AddDBTypeRule(msDateTime, ftDateTime);
In this case, in all DataSets for the DATETIME type fields with the ftDate type will be created,
and for MSQuery - with the ftDateTime type.
The point is that the priority of the rules set for the DataSet is higher than the priority of therules set for the whole connection. This allows both flexible and convenient setting of Data
Type Mapping for the whole application. There is no need to set the same rules for each
DataSet, all the general rules can be set once for the whole connection. And if a DataSet withan individual Data Type Mapping is necessary, individual rules can be set for it.

Rules for a particular field
Sometimes there is a need to set a rule not for the whole connection, and not for the wholedataset, but only for a particular field.
e.g. there is such table in a MySQL database:© 2019 Devart

112

SQL Server Data Access Components

CREATE TABLE ITEM(
ID int IDENTITY (1,1) NOT NULL PRIMARY KEY,
NAME CHAR(50),GUID CHAR(38))
The guid field contains a unique identifier. For convenient work, this identifier is expected tobe mapped to the TGuidField type in Delphi. But there is one problem, if to set the rule like
this:
MSQuery.DataTypeMap.Clear;
MSQuery.DataTypeMap.AddDBTypeRule(msChar, ftGuid);then both name and guid fields will have the ftGuid type in Delphi, that does not correspond towhat was planned. In this case, the only way is to use Data Type Mapping for a particularfield:
MSQuery.DataTypeMap.AddFieldNameRule('GUID', ftGuid);
In addition, it is important to remember that setting rules for particular fields has the highest
priority. If to set some rule for a particular field, all other rules in the Connection or DataSet willbe ignored for this field.

Ignoring conversion errors
Data Type Mapping allows mapping various types, and sometimes there can occur the
problem with that the data stored in a DB cannot be converted to the correct data of theDelphi field type specified in rules of Data Type Mapping or vice-versa. In this case, an error
will occur, which will inform that the data cannot be mapped to the specified type.
For example:

Database value

Destination field type'text value'

ftInteger

1000000

ftSmallint

15,1

ftInteger

Error
String cannot be converted
to Integer
Value is out of range
Cannot convert float to
integer

But when setting rules for Data Type Mapping, there is a possibility to ignore data conversion
errors:
MSConnection.DataTypeMap.AddDBTypeRule(msVarchar, ftInteger, True);In this case, the correct conversion is impossible. But because of ignoring data conversion
errors, Data Type Mapping tries to return values that can be set to the Delphi fields or DB
fields depending on the direction of conversion.
© 2019 Devart

Using SDAC

Database value

Destination field
type

Result'text value'

ftInteger

0

1000000

ftSmallint

32767

15,1

ftInteger

15

113

Result description
0 will be returned if
the text cannot be
converted to number
32767 is the max
value that can be
assigned to the
Smallint data type15,1 was truncated to
an integer value

Therefore ignoring of conversion errors should be used only if the conversion results are
expected.

© 1997-2019
Devart. All Rights
Reserved.

4.6

Request Support

DAC Forum

Provide Feedback

Data Encryption
SDAC has built-in algorithms for data encryption and decryption. To enable encryption, you
should attach the TCREncryptor component to the dataset, and specify the encrypted fields.
When inserting or updating data in the table, information will be encrypted on the client side inaccordance with the specified method. Also when reading data from the server, thecomponents decrypt the data in these fields "on the fly".
For encryption, you should specify the data encryption algorithm (the EncryptionAlgorithm
property) and password (the Password property). On the basis of the specified password, thekey is generated, which encrypts the data. There is also a possibility to set the key directly
using the SetKey method.
When storing the encrypted data, in addition to the initial data, you can also store additional
information: the GUID and the hash. (The method is specified in the
TCREncryptor.DataHeader property).
If data is stored without additional information, it is impossible to determine whether the datais encrypted or not. In this case, only the encrypted data should be stored in the column,
otherwise, there will be confusion because of the inability to distinguish the nature of the data.
Also in this way, the similar source data will be equivalent in the encrypted form, that is notgood from the point of view of the information protection. The advantage of this method is thesize of the initial data equal to the size of the encrypted data.
To avoid these problems, it is recommended to store, along with the data, the appropriate
GUID, which is necessary for specifying that the value in the record is encrypted and it must

© 2019 Devart

114

SQL Server Data Access Components

be decrypted when reading data. This allows you to avoid confusion and keep in the same
column both the encrypted and decrypted data, which is particularly important when using an
existing table. Also, when doing in this way, a random initializing vector is generated before
the data encryption, which is used for encryption. This allows you to receive different results
for the same initial data, which significantly increases security.
The most preferable way is to store the hash data along with the GUID and encrypted
information to determine the validity of the data and verify its integrity. In this way, if there wasan attempt to falsify the data at any stage of the transmission or data storage, whendecrypting the data, there will be a corresponding error generated. For calculating the hash
the SHA1 or MD5 algorithms can be used (the HashAlgorithm property).
The disadvantage of the latter two methods - additional memory is required for storage of theauxiliary information.
As the encryption algorithms work with a certain size of the buffer, and when storing theadditional information it is necessary to use additional memory, TCREncryptor supports
encryption of string or binary fields only (ftString, ftWideString, ftBytes, ftVarBytes, ftBlob,
ftMemo, ftWideMemo). If encryption of string fields is used, firstly, the data is encrypted, andthen the obtained binary data is converted into hexadecimal format. In this case, data storage
requires two times more space (one byte = 2 characters in hexadecimal).
Therefore, to have the possibility to encrypt other data types (such as date, number, etc.), it isnecessary to create a field of the binary or BLOB type in the table, and then convert it into thedesired type on the client side with the help of data mapping.
It should be noted that the search and sorting by encrypted fields become impossible on theserver side. Data search for these fields can be performed only on the client after decryptionof data using the Locate and LocateEx methods. Sorting is performed by setting the
TMemDataSet.IndexFieldNames property.
Example.
Let's say there is an employee list of an enterprise stored in the table with the following data:
full name, date of employment, salary, and photo. We want all these data to be stored in theencrypted form. Write a script for creating the table:
CREATE TABLE EMP(EMPNO int IDENTITY (1,1) NOT NULL PRIMARY KEY,
ENAME varbinary(2000),
HIREDATE varbinary(200),
SAL varbinary(200),
FOTO image)
As we can see, the fields for storage of the textual information, date, and floating-point
number are created with the VARBINARY type. This is for the ability to store encrypted
information, and in the case of the text field - to improve performance. Write the code to© 2019 Devart

Using SDAC

115

process this information on the client.
MSQuery.SQL.Text := 'SELECT * FROM EMP';
MSQuery.Encryption.Encryptor := MSEncryptor;
MSQuery.Encryption.Fields := 'ENAME, HIREDATE, SAL, FOTO';
MSEncryptor.Password := '11111';
MSQuery.DataTypeMap.AddFieldNameRule ('ENAME', ftString);
MSQuery.DataTypeMap.AddFieldNameRule ('HIREDATE', ftDateTime);
MSQuery.DataTypeMap.AddFieldNameRule ('SAL', ftFloat);
MSQuery.Open;© 1997-2019
Devart. All Rights
Reserved.

4.7

Request Support

DAC Forum

Provide Feedback

Working in an Unstable Network
The following settings are recommended for working in an unstable network:
TCustomDAConnection.Options.LocalFailover = True
TCustomDAConnection.Options.DisconnectedMode = True
TDataSet.CachedUpdates = True
TCustomDADataSet.FetchAll = True
TCustomDADataSet.Options.LocalMasterDetail = True
These settings minimize the number of requests to the server. Using
TCustomDAConnection.Options.DisconnectedMode allows DataSet to work without an active
connection. It minimizes server resource usage and reduces connection break probability. I.
e. in this mode connection automatically closes if it is not required any more. But every
explicit operation must be finished explicitly. That means each explicit connect must be
followed by explicit disconnect. Read Working with Disconnected Mode topic for more
information.
Setting the FetchAll property to True allows to fetch all data after cursor opening and to close
connection. If you are using master/detail relationship, we recommend to set the
LocalMasterDetail option to True.
It is not recommended to prepare queries explicitly. Use the CachedUpdates mode for
DataSet data editing. Use the TCustomDADataSet.Options.UpdateBatchSize property to
reduce the number of requests to the server.
If a connection breaks, a fatal error occurs, and the OnConnectionLost event will be raised if
the following conditions are fulfilled:
There are no active transactions;
There are no opened and not fetched datasets;
There are no explicitly prepared datasets or SQLs.
If the user does not refuse suggested RetryMode parameter value (or does not use the
OnConnectionLost event handler), SDAC can implicitly perform the following operations:© 2019 Devart

116

SQL Server Data Access Components

Connect;
DataSet.ApplyUpdates;
DataSet.Open;
I.e. when the connection breaks, implicit reconnect is performed and the corresponding
operation is reexecuted. We recommend to wrap other operations in transactions and fulfill
their reexecuting yourself.
The using of Pooling in Disconnected Mode allows to speed up most of the operations
because of connecting duration reducing.

See Also
FailOver demoWorking with Disconnected Mode
TCustomDAConnection.Options
TCustomDAConnection.Pooling© 1997-2019
Devart. All Rights
Reserved.

4.8

Request Support

DAC Forum

Provide Feedback

Disconnected Mode
In disconnected mode a connection opens only when it is required. After performing all server
calls connection closes automatically until next server call is required. Datasets remain
opened when connection closes. Disconnected Mode may be useful for saving server
resources and operating in an unstable or expensive network. Drawback of using
disconnected mode is that each connection establishing requires some time for authorization.
If connection is often closed and opened it can slow down application work. We recommend
to use pooling to solve this problem. For additional information see
TCustomDAConnection.Pooling.
To enable disconnected mode set TCustomDAConnection.Options.DisconnectedMode toTrue.
In disconnected mode a connection is opened for executing requests to the server (if it was
not opened already) and is closed automatically if it is not required any more. If the connection
was explicitly opened (the Connect method was called or the Connected property was
explicitly set to True), it does not close until the Disonnect method is called or the Connected
property is set to False explicitly.
The following settings are recommended to use for working in disconnected mode:
TDataSet.CachedUpdates = True
TCustomDADataSet.FetchAll = True
TCustomDADataSet.Options.LocalMasterDetail = True
These settings minimize the number of requests to the server.
© 2019 Devart

Using SDAC

117

Disconnected mode features
If you perform a query with the FetchAll option set to True, connection closes when all data is
fetched if it is not used by someone else. If the FetchAll option is set to false, connection does
not close until all data blocks are fetched.
If explicit transaction was started, connection does not close until the transaction iscommitted or rolled back.
If the query was prepared explicitly, connection does not close until the query is unprepared or
its SQL text is changed.

See Also
TCustomDAConnection.Options
FetchAll
Devart.Sdac.TMSQuery.LockMode
TCustomDAConnection.Pooling
TCustomDAConnection.Connect
TCustomDAConnection.Disonnect
Working in unstable network© 1997-2019
Devart. All Rights
Reserved.

4.9

Request Support

DAC Forum

Provide Feedback

Performance of Obtaining Data
If you need to obtain an updatable recordset in your application and show it in a grid, the sizeof the data to be transferred from the server is very important. As a rule such recordsets are
not that big, as it is hard for a user to handle tables containing thousands of records. In thiscase the most appropriate is the default SDAC behavior, when the CursorType property of thedataset is set to ctDefaultResultSet, and the FetchAll property is set to True.
Just the the same settings must be used, irrespectively of the data size, for the datasets
serving as lookup sources for lookup fields.
If you want to see the result of a query execution returning a large amount of data
immediately, you should set the FetchAll property to False, or use server cursors. In bothcases only few records are fetched to the client immediately after opening. Other records arefetched on demand.
There are brief descriptions of advantages and disadvantages for different settings below.
CursorType = ctDefaultResultSet, FetchAll = True - This is the default
SDAC settings. Opening is pretty slow, but navigation is fast. All records are fetched on© 2019 Devart

118

SQL Server Data Access Components

opening, and cached on the client.
CursorType = ctDefaultResultSet, FetchAll = False - Opening is fastirrespectively of the total records count. Only several records are fetched on opening. You
can specify the number of records in the FetchRows property. Other records are retrieved
from the server on demand, and cached. Additional records may be demanded whenscrolling through the linked grid, calling to Locate, Last, etc.
However, these settings may cause certain problems related transaction conflict anddeadlocks. For more details please refer to the description of theTCustomMSDataSet.FetchAll property.
CursorType in [ctStatic, ctKeyset, ctDynamic] - All these cursors areserver cursors. They are characterized by quick opening, low client memory utilization, andslow navigation. Only data required at the moment is cached. For more details about thesecursor types please refer to the description of the CursorType property.
If you need to get only certain values from the server, for example only record count, it is more
effective to execute a query with parameters:
SET :Cnt = (SELECT COUNT(*) FROM ...)
instead of queries like this one:
SELECT COUNT(*) FROM ...
Note: Only the ctDefaultResultSet cursor allows executing batches of queries.

See Also
FetchAll
CursorType
The ServerCursors demo in the SDAC General demo
The FetchAll demo in the SDAC General demo

© 1997-2019
Devart. All Rights
Reserved.

4.10

Request Support

DAC Forum

Provide Feedback

Batch Operations
Data amount processed by modern databases grows steadily. In this regard, there is anacute problem – database performance. Insert, Update and Delete operations have to be
performed as fast as possible. Therefore Devart provides several solutions to speed up
processing of huge amounts of data. So, for example, insertion of a large portion of data to a
DB is supported in the TMSLoader. Unfortunately, TMSLoader allows to insert data only – it
can’t be used for updating and deleting data.

© 2019 Devart

Using SDAC

119

The new version of Devart Delphi Data Access Components introduces the new mechanism
for large data processing — Batch Operations. The point is that just one parametrized Modify
SQL query is executed. The plurality of changes is due to the fact that parameters of such aquery will be not single values, but a full array of values. Such approach increases the speedof data operations dramatically. Moreover, in contrast to using TMSLoader, Batch operations
can be used not only for insertion, but for modification and deletion as well.
Let’s have a better look at capabilities of Batch operations with an example of the
BATCH_TEST table containing attributes of the most popular data types.

Batch_Test table generating scripts
CREATE TABLE BATCH_TEST
(
ID
INT,
F_INTEGER INT,
F_FLOAT FLOAT,F_STRING VARCHAR(250),
F_DATE DATETIME,CONSTRAINT PK_BATCH_TEST PRIMARY KEY (ID))

Batch operations execution
To insert records into the BATCH_TEST table, we use the following SQL query:

INSERT INTO BATCH_TEST VALUES (:ID, :F_INTEGER, :F_FLOAT, :F_STRING, :F_DATWhen a simple insertion operation is used, the query parameter values look as follows:

Parameters:ID
1:F_INTEGER
100:F_FLOAT
2.5:F_STRING:F_DATE‘String Value 1' 01.09.2015

After the query execution, one record will be inserted into the BATCH_TEST table.
When using Batch operations, the query and its parameters remain unchanged. However,parameter values will be enclosed in an array:

Parameters
:ID
1
2
3
4
5

© 2019 Devart:F_INTEGER
100
200
300
400
500

:F_FLOAT
2.5
3.15
5.08
7.53430.4555:F_STRING‘String Value 1'‘String Value 2'‘String Value 3'‘String Value 4'‘String Value 5':F_DATE
01.09.2015
01.01.2000
09.09.2010
10.10.2015
01.09.2015

120

SQL Server Data Access Components

Now, 5 records are inserted into the table at a time on query execution.
How to implement a Batch operation in the code?

Batch INSERT operation sample
Let’s try to insert 1000 rows to the BATCH_TEST table using a Batch Insert operation:var
i: Integer;
begin// describe the SQL query
MSQuery1.SQL.Text := 'INSERT INTO BATCH_TEST VALUES (:ID, :F_INTEGER, :F_F// define the parameter types passed to the query :MSQuery1.Params[0].DataType := ftInteger;
MSQuery1.Params[1].DataType := ftInteger;
MSQuery1.Params[2].DataType := ftFloat;
MSQuery1.Params[3].DataType := ftString;
MSQuery1.Params[4].DataType := ftDateTime;// specify the array dimension:
MSQuery1.Params.ValueCount := 1000;// populate the array with parameter values:
for i := 0 to MSQuery1.Params.ValueCount - 1 do begin
MSQuery1.Params[0][i].AsInteger := i + 1;
MSQuery1.Params[1][i].AsInteger := i + 2000 + 1;
MSQuery1.Params[2][i].AsFloat := (i + 1) / 12;
MSQuery1.Params[3][i].AsString := 'Values ' + IntToStr(i + 1);
MSQuery1.Params[4][i].AsDateTime := Now;end;// insert 1000 rows into the BATCH_TEST table
MSQuery1.Execute(1000);
end;
This command will insert 1000 rows to the table with one SQL query using the prepared arrayof parameter values. The number of inserted rows is defined in the Iters parameter of the
Execute(Iters: integer; Offset: integer = 0) method. In addition, you can pass anotherparameter – Offset (0 by default) – to the method. The Offset parameter points the arrayelement, which the Batch operation starts from.
We can insert 1000 records into the BATCH_TEST table in 2 ways.
All 1000 rows at a time:
MSQuery1.Execute(1000);
2×500 rows:// insert first 500 rows
MSQuery1.Execute(500, 0);// insert next 500 rows
MSQuery1.Execute(500, 500);
500 rows, then 300, and finally 200:// insert 500 rows
MSQuery1.Execute(500, 0);© 2019 Devart

Using SDAC

121// insert next 300 rows starting from 500
MSQuery1.Execute(300, 500);// insert next 200 rows starting from 800
MSQuery1.Execute(200, 800);

Batch UPDATE operation sample
With Batch operations we can modify all 1000 rows of our BATCH_TEST table just thissimple:var
i: Integer;
begin// describe the SQL query
MSQuery1.SQL.Text := 'UPDATE BATCH_TEST SET F_INTEGER=:F_INTEGER, F_FLOAT=// define parameter types passed to the query:
MSQuery1.Params[0].DataType := ftInteger;
MSQuery1.Params[1].DataType := ftFloat;
MSQuery1.Params[2].DataType := ftString;
MSQuery1.Params[3].DataType := ftDateTime;
MSQuery1.Params[4].DataType := ftInteger;// specify the array dimension:
MSQuery1.Params.ValueCount := 1000;// populate the array with parameter values:
for i := 0 to 1000 - 1 do begin
MSQuery1.Params[0][i].AsInteger := i - 2000 + 1;
MSQuery1.Params[1][i].AsFloat := (i + 1) / 100;
MSQuery1.Params[2][i].AsString := 'New Values ' + IntToStr(i + 1);
MSQuery1.Params[3][i].AsDateTime := Now;
MSQuery1.Params[4][i].AsInteger := i + 1;
end;// update 1000 rows in the BATCH_TEST table
MSQuery1.Execute(1000);end;

Batch DELETE operation sample
Deleting 1000 rows from the BATCH_TEST table looks like the following operation:var
i: Integer;
begin// describe the SQL query
MSQuery1.SQL.Text := 'DELETE FROM BATCH_TEST WHERE ID=:ID';// define parameter types passed to the query:
MSQuery1.Params[0].DataType := ftInteger;// specify the array dimension
MSQuery1.Params.ValueCount := 1000;// populate the arrays with parameter values
for i := 0 to 1000 - 1 do
MSQuery1.Params[0][i].AsInteger := i + 1;// delete 1000 rows from the BATCH_TEST table
MSQuery1.Execute(1000);
end;© 2019 Devart

122

SQL Server Data Access Components

Performance comparison
The example with BATCH_TEST table allows to analyze execution speed of normal
operations with a database and Batch operations:Operation TypeInsertUpdateDeleteThe less, the better.

25 000 records
Standard Operation
Batch Operation (sec.)(sec.)
19.19
3.09
20.22
7.67
18.28
3.14

It should be noted, that the retrieved results may differ when modifying the same table ondifferent database servers. This is due to the fact that operations execution speed may differ
depending on the settings of a particular server, its current workload, throughput, network
connection, etc.

Thing you shouldn’t do when accessing parameters in Batch operations!
When populating the array and inserting records, we accessed query parameters by index. It
would be more obvious to access parameters by name:for i := 0 to 9999 do begin
MSQuery1.Params.ParamByName('ID')[i].AsInteger := i + 1;
MSQuery1.Params.ParamByName('F_INTEGER')[i].AsInteger := i + 2000 + 1;
MSQuery1.Params.ParamByName('F_FLOAT')[i].AsFloat := (i + 1) / 12;
MSQuery1.Params.ParamByName('F_STRING')[i].AsString := 'Values ' + IntToSt
MSQuery1.Params.ParamByName('F_DATE')[i].AsDateTime := Now;
end;
However, the parameter array would be populated slower, since you would have to define theordinal number of each parameter by its name in each loop iteration. If a loop is executed
10000 times – performance loss can become quite significant.

© 1997-2019
Devart. All Rights
Reserved.

4.11

Request Support

DAC Forum

Provide Feedback

Increasing PerformanceThis topic considers basic stages of working with DataSet and ways to increase performanceon each of these stages.

Connect© 2019 Devart

Using SDAC

123

If your application performs Connect/Disconnect operations frequently, additional
performance can be gained using pooling mode (TCustomDAConnection.Pooling = True). It
reduces connection reopening time greatly (hundreds times). Such situation usually occurs in
web applications.

ExecuteIf your application executes the same query several times, you can use theTCustomDADataSet.Prepare method or set the TDADataSetOptions.AutoPrepare property toincrease performance. For example, it can be enabled for Detail dataset in Master/Detail
relationship or for update objects in TDAUpdateSQL. The performance gain achieved this way
can be anywhere from several percent to several times, depending on the situation.
To execute SQL statements a TMSSQL component is more preferable than TMSQuery. It
can give several additional percents performance gain.
If the TCustomDADataSet.Options.StrictUpdate option is set to False, the RowsAffected
property is not calculated and becomes equal zero. This can improve performance of query
executing, so if you need to execute many data updating statements at once and you don't
mind affected rows count, set this option to False.

Open
If you don't need to edit the dataset, you can set its ReadOnly property to increase its opening
speed. In that case, an additional information, required for INSERT, UPDATE, and DELETE
statement generation, will not be requested.

Fetch
In some situations you can increase performance a bit by using
TCustomDADataSet.Options.CompressBlobMode.
You can also tweak your application performance by using the following properties ofTCustomDADataSet descendants:
FetchRows
Options.FlatBuffers
Options.LongStrings
UniDirectional
See the descriptions of these properties for more details and recommendations.

Navigate
The Locate function works faster when dataset is locally sorted on KeyFields fields. Local© 2019 Devart

124

SQL Server Data Access Components

dataset sorting can be set with the IndexFieldNames property. Performance gain can be large
if the dataset contains a large number of rows.
Lookup fields work faster when lookup dataset is locally sorted on lookup Keys.
Setting the TDADataSetOptions.CacheCalcFields property can improve performance whenlocally sorting and locating on calculated and lookup fields. It can be also useful whencalculated field expressions contain complicated calculations.
Setting the TDADataSetOptions.LocalMasterDetail option can improve performance greatly
by avoiding server requests on detail refreshes. Setting the TDADataSetOptions.DetailDelay
option can be useful for avoiding detail refreshes when switching master DataSet records
frequently.

UpdateIf your application updates datasets in the CachedUpdates mode, then setting theTCustomDADataSet.Options.UpdateBatchSize option to more than 1 can improve
performance several hundred times more by reducing the number of requests to the server.
You can also increase the data sending performance a bit (several percents) by using
Dataset.UpdateObject.ModifyObject, Dataset.UpdateObject, etc. Little additional performance
improvement can be reached by setting the AutoPrepare property for these objects.

InsertIf you are about to insert a large number of records into a table, you should use the
T:Devart.Sdac.TMSLoader component instead of Insert/Post methods, or execution of the
INSERT commands multiple times in a cycle. Sometimes usage of
T:Devart.Sdac.TMSLoader improves performance several times.

See Also
Performance of obtaining data

© 1997-2019
Devart. All Rights
Reserved.

4.12

Request Support

DAC Forum

Provide Feedback

MacrosMacros help you to change SQL statements dynamically. They allow partial replacement of
the query statement by user-defined text. Macros are identified by their names which are thenreferred from SQL statement to replace their occurrences for associated values.
First step is to assign macros with their names and values to a dataset object.
Then modify SQL statement to include macro names into desired insertion points. Prefix© 2019 Devart

Using SDAC

125

each name with & ("at") sign to let SDAC discriminate them at parse time. Resolved SQL
statement will hold macro values instead of their names but at the right places of theiroccurrences. For example, having the following statement with the TableName macro name:
SELECT * FROM &TableName
You may later assign any actual table name to the macro value property leaving your SQL
statement intact.
Query1.SQL.Text := 'SELECT * FROM &TableName';
Query1.MacroByName('TableName').Value := 'Dept';
Query1.Open;SDAC replaces all macro names with their values and sends SQL statement to the serverwhen SQL execution is requested.
Note that there is a difference between using TMacro AsString and Value properties. If you set
macro with the AsString property, it will be quoted. For example, the following statements will
result in the same result Query1.SQL property value.
Query1.MacroByName('StringMacro').Value := '''A string''';Query1.MacroByName('StringMacro').AsString := 'A string';
Macros can be especially useful in scripts that perform similar operations on different objects.
You can use macros that will be replaced with an object name. It allows you to have the same
script text and to change only macro values.
You may also consider using macros to construct adaptable conditions in WHERE clauses ofyour statements.

See Also
TMacroTCustomDADataSet.MacroByName
TCustomDADataSet.Macros© 1997-2019
Devart. All Rights
Reserved.

4.13

Request Support

DAC Forum

Provide Feedback

DataSet Manager

DataSet Manager window
The DataSet Manager window displays the datasets in your project. You can use the DataSet
Manager window to create a user interface (consisting of data-bound controls) by dragging
items from the window onto forms in your project. Each item has a drop-down control list
where you can select the type of control to create prior to dragging it onto a form. You cancustomize the control list with additional controls, including the controls you have created.
© 2019 Devart

126

SQL Server Data Access Components

Using the DataSet Manager window, you can:Create forms that display data by dragging items from the DataSet Manager window onto
forms.
Customize the list of controls available for each data type in the DataSet Manager window.
Choose which control should be created when dragging an item onto a form in your
Windows application.
Create and delete TField objects in the DataSets of your project.

Opening the DataSet Manager window
You can display the DataSet Manager window by clicking DataSet Manager on the Tools
menu. You can also use IDE desktop saving/loading to save DataSet Manager window
position and restore it during the next IDE loads.

Observing project DataSets in the DataSet Manager
Window
By default DataSet Manager shows DataSets of currently open forms. It can also extract© 2019 Devart

Using SDAC

127

DataSets from all forms in the project. To use this, click Extract DataSets from all forms inproject button. This settings is remembered. Note, that using this mode can slow down
opening of the large projects with plenty of forms and DataSets. Opening of such projects canbe very slow in Delphi 6 and Borland Developer Studio 2006 and can take up to several tensof minutes.
DataSets can be grouped by form or connection. To change DataSet grouping click theGrouping mode button or click a down. You can also change grouping mode by selecting
required mode from the DataSet Manager window popup menu.

Creating Data-bound Controls
You can drag an item from the DataSet Manager window onto a form to create a new databound control. Each node in the DataSet Manager window allows you to choose the type ofcontrol that will be created when you drag it onto a form. You must choose between a Gridlayout, where all columns or properties are displayed in a TDataGrid component, or a Details
layout, where all columns or properties are displayed in individual controls.
To use grid layout drag the dataset node on the form. By default TDataSource and TDBGrid
components are created. You can choose the control to be created prior to dragging byselecting an item in the DataSet Manager window and choosing the control from the item's
drop-down control list.

© 2019 Devart

128

SQL Server Data Access Components

To use Details layout choose Details from the DataSet node drop-down control list in the
DataSet Manager window. Then select required controls in the drop-down control list for each
DataSet field. DataSet fields must be created. After setting required options you can drag the
DataSet to the form from the DataSet wizard. DataSet Manager will create TDataSourcecomponent, and a component and a label for each field.

© 2019 Devart

Using SDAC

129

Adding custom controls to the DataSet Manager window
To add custom control to the list click the Options button on the DataSet Manager toolbar. A
DataSet Manager - Customize controls dialog will appear. Using this dialog you can set
controls for the DataSets and for the DataSet fields of different types. To do it, click DataSets
node or the node of field of required type in DB objects groups box and use Add and Remove
buttons to set required control list. You can also set default control by selecting it in the list of
assigned DB controls and pressing Default button.

The default configuration can easily be restored by pressing Reset button in the DataSet
Manager - Options dialog.

Working with TField objects
DataSet Manager allows you to create and remove TField objects. DataSet must be active towork with its fields in the DataSet Manager. You can add fields, based on the database table
columns, create new fields, remove fields, use drag-n-drop to change fields order.
To create a field based on the database table column right-click the Fields node and selectCreate Field from the popup menu or press <Insert>. Note that after you add at least one field© 2019 Devart

130

SQL Server Data Access Components

manually, DataSet fields corresponding to data fields will not be generated automatically when
you drag the DataSet on the form, and you can not drag such fields on the form. To add allavailable fields right-click the Fields node and select Add all fields from the popup menu.
To create new field right-click the Fields node and select New Field from the popup menu orpress <Ctrl+Insert>. The New Field dialog box will appear. Enter required values and press
OK button.
To delete fields select these fields in the DataSet Manager window and press <Delete>.
DataSet Manager allows you to change view of the fields displayed in the main window. Openthe Customize controls dialog, and jump to the Options page.

You can chose what information will be added to names of the Field and Data Field objects inthe main window of DataSet Manager. Below you can see the example.

© 1997-2019
Devart. All Rights
Reserved.

4.14

Request Support

DAC Forum

Provide Feedback

SQL Server Compact Edition
SDAC supports SQL Server Compact Edition. SQL Server Compact Edition is an easy toinstall server for using by applications that do not require multi-user work with server. For© 2019 Devart

Using SDAC

131

example, SQL Server Compact Edition can be used on the local computers if there is nopermanent connection to the main database, for money access machines, automatic cash
desks, different electronic facilities and so on. Please refer to SQL Server Compact Edition
Books Online for more details about the features and usage of this server edition.
To work with SQL Server Compact Edition you should change the Provider property of theconnection options to prCompact, or use the TMSCompactConnection component.
Database filename should be assigned to the Database property. If the file does not exists, itwill be automatically created on the connection opening. The Password property is used toconnect to or create a database.
Use the Encrypt option to specify if a database will be created or encrypted. If this option is
set to True, the Password property must be assigned.
The TMSStoredProc component can not work with the SQL Server Compact Edition because
this server edition does not support stored procedures.
Not all values of ObjectType property are supported by TMSMetaData component with the
SQL Server Compact Edition.
Please refer to MSSQLCompact Demo to get a sample.

See Also
MSSQLCompact Demo
TMSCompactConnection
TMSConnection.Options© 1997-2019
Devart. All Rights
Reserved.

4.15

Request Support

DAC Forum

Provide Feedback

Working with User Defined Types (UDT)

What is UDT
Microsoft SQL Server 2005 introduced a new possibility to extend the standard type set withdata types created in CLR. These types can be used to define columns in tables andvariables, in triggers, stored procedures, and functions. UDT is an assembly containing aclass written on any programming language. The language must support .NET Framework
version 2.0 or higher.

SQL Server requirements
User Defined Types are supported by SQL Server 2005 and higher versions. It is necessary
to make sure that CLR integration of the server is enabled. By default in SQL Server it isdisabled. You can check whether the CLR integration is currently enabled running the© 2019 Devart

132

SQL Server Data Access Components

following system routine:
sp_configure 'clr enabled'
This routine returns a dataset. If the value of the run_value field equals to 0, you need toenable CLR running the same routine with one additional parameter:
sp_configure 'clr enabled', 1
GO
RECONFIGURE
GO
Calling RECONFIGURE is required when applying a new value.

Client requirements
Here are the client requirements:.NET Framework version 2.00 or higher;
Microsoft SQL Native Client;
the assembly implementing UDT in an accessible place;the Devart.Sdac.UDTProxy.dll in an accessible place. This file can be found in the Bin
subfolder of the SDAC installation directory.
An accessible place means one of the following locations:
1. The application directory (the preferable way);
2. Global Assembly Cache (GAC);
3. Any directory registered in the PATH system variable.

Creating UDT
You can create an assembly containing UDT using any programming language that supports.NET Framework version 2.00 and higher.
There is an example of a UDT implementation within SDAC demos. You can find it in the UDT
demo directory of the SDAC General demo. The sample UDT is called Square. It is
implemented with Microsoft Visual Studio 2005. There are both sources and the binary
assembly in the Square directory.

Using UDTUDT can be used only in Win32 application.
In order to use a UDT in SQL Server, first of all you should register the UDT. This can bedone by executing CREATE ASSEMBLY command. After the assembly was registered, it isnecessary to create a new type from the registered assembly using the CREATE TYPE
command. Now you can use the name of the registered type in SQL commands like© 2019 Devart

Using SDAC

133

CREATE TABLE.
In order to provide native access to the UDT fields in your application, the client requirements
should be fulfilled. Also make sure that TMSConnection is setup to use SQL Native Client as
a provider ( TMSConnection.Options.Provider should be equal to prNativeClient). If all settings
are applied correctly, UDT fields are described as mapped to the TMSUDTField class.
Otherwise, UDT fields are mapped to TVarBytesField. You can access specific properties of
UDT using the AsUDT property of TMSUDTField. It may look like the code below (this code istaken from the UDT demo project included in the SDAC General demo):
var
Square: variant;
begin
MSQuery.Edit;
Square := (MSQuery.FieldByName('c_square') as TMSUDTField).AsUDT;
Square.BaseX := StrToInt(edBaseX.Text);
Square.BaseY := StrToInt(edBaseY.Text);
Square.Side := StrToInt(edSide.Text);
MSQuery.Post;
BaseX, BaseY, and Length are properties of the Square class.
For an example see the UDT demo project included in the SDAC General demo.

See Also
MSSQLCompact Demo
TMSCompactConnection
TMSConnection.Options© 1997-2019
Devart. All Rights
Reserved.

4.16

Request Support

DAC Forum

Provide Feedback

TMSTransaction Component
The TMSTransaction component is designed to manage distributed transactions. Distributed
transactions can be performed to one or more connections connected to the same or todifferent databases or servers. Within each connection a separate branch of the transaction
is performed. TMSTransaction is based on the Microsoft Distributed Transaction Coordinator(MSDTC) functionality. Transactions can be managed by StartTransaction, Commit, andRollback methods of TMSTransaction. For more information on distributed transactions and
MSDTC please refer to MSDN.
TMSTransaction does not support local transactions.To control local transactions you should
use methods of the TMSConnection component.
The example below demonstrates using distributed transaction coordinated by Microsoft
Distributed Transaction Coordinator:
begin© 2019 Devart

134

SQL Server Data Access Components

MSConnection1.Connect;
MSConnection2.Connect;
MSTransaction.AddConnection(MSConnection1);
MSTransaction.AddConnection(MSConnection2);
MSTransaction.StartTransaction;
MSSQL1.Connection := MSConnection1;
MSSQL2.Connection := MSConnection2;
try
MSSQL1.Execute;MSSQL2.Execute;
MSTransaction.Commit;
exceptMSTransaction.Rollback;
end;
end;
After both connections are established, they are added to the list of connections managed by
MSTransaction. Call to StartTransaction makes both TMSConnections components work inthe same distributed transaction. After MSSQL1 and MSSQL2 are executed,
MSTransaction.Commit ensures that all changes to both databases are committed. If an
exception occurs during execution, MSTransaction.Rollback restores both databases to theirinitial state.

See Also
TMSTransaction© 1997-2019
Devart. All Rights
Reserved.

4.17

Request Support

DAC Forum

Provide Feedback

DBMonitor
To extend monitoring capabilities of SDAC applications there is an additional tool called
DBMonitor. It is provided as an alternative to Borland SQL Monitor which is also supported by
SDAC.
DBMonitor is an easy-to-use tool to provide visual monitoring of your database applications.
DBMonitor has the following features:
multiple client processes tracing;
SQL event filtering (by sender objects);
SQL parameter and error tracing.
DBMonitor is intended to hamper an application being monitored as little as possible.
To trace your application with DB Monitor you should follow these steps:
drop TMSSQLMonitor component onto the form;
turn moDBMonitor option on;
set to True the Debug property for components you want to trace;© 2019 Devart

Using SDAC

135

start DBMonitor before running your program.

© 1997-2019
Devart. All Rights
Reserved.

4.18

Request Support

DAC Forum

Provide Feedback

Writing GUI Applications with SDAC
SDAC GUI part is standalone. This means that to make GUI elements such as SQL cursors,connect form, connect dialog etc. available, you should explicitly include SdacVcl unit in yourapplication. This feature is needed for writing console applications.

Delphi and C++Builder
By default SDAC does not require Forms, Controls and other GUI related units. Only
TMSConnectDialog and TMSAlerter components require the Forms unit.

© 1997-2019
Devart. All Rights
Reserved.

4.19

Request Support

DAC Forum

Provide Feedback

Connection Pooling
Connection pooling enables an application to use a connection from a pool of connections
that do not need to be reestablished for each use. Once a connection has been created andplaced in a pool, an application can reuse that connection without performing the complete
connection process.
Using a pooled connection can result in significant performance gains, because applications
can save the overhead involved in making a connection. This can be particularly significant for
middle-tier applications that connect over a network or for applications that connect anddisconnect repeatedly, such as Internet applications.
To use connection pooling set the Pooling property of the TCustomDAConnection component
to True. Also you should set the PoolingOptions of the TCustomDAConnection. These
options include MinPoolSize, MaxPoolSize, Validate, ConnectionLifeTime. Connections
belong to the same pool if they have identical values for the following parameters:
MinPoolSize, MaxPoolSize, Validate, ConnectionLifeTime, Server, Username, Password ,Database, IsolationLevel, Authentication, QuotedIdentifier, Provider, Language, Encrypt,
PersistSecurityInfo, AutoTranslate, NetworkLibrary, ApplicationName, WorkstationID,
PacketSize . When a connection component disconnects from the database the connection
actually remains active and is placed into the pool. When this or another connection
component connects to the database it takes a connection from the pool. Only when there
are no connections in the pool, new connection is established.
Connections in the pool are validated to make sure that a broken connection will not be© 2019 Devart

136

SQL Server Data Access Components

returned for the TCustomDAConnection component when it connects to the database. The
pool validates connection when it is placed to the pool (e. g. when the TCustomDAConnection
component disconnects). If connection is broken it is not placed to the pool. Instead the poolfrees this connection. Connections that are held in the pool are validated every 30 seconds.
All broken connections are freed. If you set the PoolingOptions.Validate to True, a connection
also will be validated when the TCustomDAConnection component connects and takes aconnection from the pool. When some network problem occurs all connections to the
database can be broken. Therefore the pool validates all connections before any of them will
be used by a TCustomDAConnection component if a fatal error is detected on one
connection.
The pool frees connections that are held in the pool during a long time. If no new connections
are placed to the pool it becomes empty after approximately 4 minutes. This pool behaviour isintended to save resources when the count of connections in the pool exceeds the count thatis needed by application. If you set the PoolingOptions.MinPoolSize property to a non-zerovalue, this prevents the pool from freeing all pooled connections. When connection count in
the pool decreases to MinPoolSize value, remaining connection will not be freed except if they
are broken.
The PoolingOptions.MaxPoolSize property limits the count of connections that can be activeat the same time. If maximum count of connections is active and someTCustomDAConnection component tries to connect, it will have to wait until any ofTCustomDAConnection components disconnect. Maximum wait time is 30 seconds. If active
connections' count does not decrease during 30 seconds, the TCustomDAConnection
component will not connect and an exception will be raised.
You can limit the time of connection's existence by setting the
PoolingOptions.ConnectionLifeTime property. When the TCustomDAConnection component
disconnects, its internal connection will be freed instead of placing to the pool if thisconnection is active during the time longer than the value of the
PoolingOptions.ConnectionLifeTime property. This property is designed to make loadbalancing work with the connection pool.
To force freeing of a connection when the TCustomDAConnection component disconnects,
the RemoveFromPool method of TCustomDAConnection can be used. You can also free allconnection in the pool by using the class procedures Clear or AsyncClear of
TMSConnectionPoolManager. These procedures can be useful when you know that allconnections will be broken for some reason.
It is recommended to use connection pooling with the DisconnectMode option of theTCustomDAConnection component set to True. In this case internal connections can beshared between TCustomDAConnection components. When some operation is performedon the TCustomDAConnection component (for example, an execution of SQL statement) this© 2019 Devart

Using SDAC

137

component will connect using pooled connection and after performing operation it will
disconnect. When an operation is performed on another TCustomDAConnection component
it can use the same connection from the pool.

See Also
TCustomDAConnection.Pooling
TCustomDAConnection.PoolingOptions
Working with Disconnected Mode

© 1997-2019
Devart. All Rights
Reserved.

4.20

Request Support

DAC Forum

Provide Feedback

Compatibility with Previous Versions
We always try to keep SDAC compatible with previous versions, but sometimes we have tochange the behaviour of SDAC in order to enhance its functionality, or avoid bugs. This topic
describes such changes, and how to revert the old SDAC behaviour. We strongly
recommend not to turn on the old behaviour of SDAC. Use options described below only ifchanges applied to SDAC crashed your existent application.
Values of the options described below should be assigned in the initialization section of oneof the units in your project.

DBAccess.BaseSQLOldBehavior:
The BaseSQL property is similar to the SQL property, but it does not store changes made by
AddWhere, DeleteWhere, and SetOrderBy methods. After assigning an SQL text andmodifying it by one of these methods, all subsequent changes of the SQL property will not bereflected in the BaseSQL property. This behavior was changed in SDAC 3.55.2.22. To restore
old behavior, set the BaseSQLOldBehavior variable to True.

DBAccess.SQLGeneratorCompatibility:
If the manually assigned RefreshSQL property contains only "WHERE" clause, SDAC uses
the value of the BaseSQL property to complete the refresh SQL statement. In this situation all
modifications applied to the SELECT query by functions AddWhere, DeleteWhere are nottaken into account. This behavior was changed in SDAC 4.00.0.4. To restore the old behavior,
set the BaseSQLOldBehavior variable to True.

MemDS.SendDataSetChangeEventAfterOpen:Starting with SDAC 4.20.0.12, the DataSetChange event is sent after the dataset gets open. It
was necessary to fix a problem with disappeared vertical scrollbar in some types of DB© 2019 Devart

138

SQL Server Data Access Components

aware grids. This problem appears only under Windows XP when visual styles are enabled.
To disable sending this event, change the value of this variable to False.

MemDS.DoNotRaiseExcetionOnUaFail:
Starting with SDAC 4.20.0.13, if the OnUpdateRecord event handler sets the UpdateAction
parameter to uaFail, an exception is raised. The default value of UpdateAction is uaFail. So,
the exception will be raised when the value of this parameter is left unchanged.
To restore the old behaviour, set DoNotRaiseExcetionOnUaFail to True.

MSAccess.__UseUpdateOptimization
In SDAC 4.00.0.4 update statements execution was optimized. This optimization changed
behaviour of affected rows count retrieval for tables with triggers. If a trigger performs
modifications of other records reacting on a modification in the underlying table, SQL Server
sends several values of affected rows count (including for modifications made by the trigger).
Prior to SDAC 4.00.0.4 the first value was considered as affected rows count, when in SDAC
4.00.0.4 and higher - the last value. However neither of these two approaches can beconsidered correct, as there can be triggers that snap into action both before modification andafter modification. There is no way to determine which of the values returned by SQL Serveris the correct value of affected rows count. Therefore we do not recommend using the
RowsAffected property when updating tables with triggers.
StrictUpdate mode is based on RowsAffected, therefore we also do not recommend using
StrictUpdate when updating tables with triggers.
If you want to disable this optimization, set the __UseUpdateOptimization variable to False.

TCustomMSConnectionOptions.UseWideMemos:
Set TCustomMSConnectionOptions.UseWideMemos to False to disable mapping of NText
database data type to ftWideMemo data type.

OLEDBAccess.ParamsInfoOldBehavior:Starting with SDAC 3.70.1.26 preparing and the first call of a stored procedure werecombined for performance optimization. This requires the necessity of setting the parameter
type and data type of all parameters before preparing. In order to revert the old behaviour withpreparation and parameters, the OLEDBAccess unit should be added to the uses clause of aunit in an application, and the following line should be added to the initialization section of theunit:
ParamsInfoOldBehavior := True.

DBAccess.ParamStringAsAnsiString:© 2019 Devart

Using SDAC

139

This variable has sense for Delphi 2009 and higher.
Set its value to True to use the AsAnsiString property when setting the parameter value
through TDAParam.AsString. Otherwise the AsWideString property is used. The default value
is False.

© 1997-2019
Devart. All Rights
Reserved.

4.21

Request Support

DAC Forum

Provide Feedback

64-bit Development with Embarcadero RAD Studio XE2

RAD Studio XE2 Overview
RAD Studio XE2 is the major breakthrough in the line of all Delphi versions of this product. It
allows deploying your applications both on Windows and Mac OS platforms. Additionally, it is
now possible to create 64-bit Windows applications to fully benefit from the power of new
hardware. Moreover, you can create visually spectacular applications with the help of theFireMonkey GPU application platform.
Its main features are the following:
Windows 64-bit platform support;
Mac OS support;
FireMonkey application development platform;
Live data bindings with visual components;
VCL styles for Windows applications.
For more information about RAD Studio XE2, please refer to World Tour.

Changes in 64-bit Application Development
64-bit platform support implies several important changes that each developer must keep inmind prior to the development of a new application or the modernization of an old one.
GeneralRAD Studio XE2 IDE is a 32-bit application. It means that it cannot load 64-bit packages atdesign-time. So, all design-time packages in RAD Studio XE2 IDE are 32-bit.
Therefore, if you develop your own components, you should remember that for the purpose ofdeveloping components with the 64-bit platform support, you have to compile run-time
packages both for the 32- and 64-bit platforms, while design-time packages need to becompiled only for the 32-bit platform. This might be a source of difficulties if your package issimultaneously both a run-time and a design-time package, as it is more than likely that thispackage won't be compiled for the 64-bit platform. In this case, you will have to separate your© 2019 Devart

140

SQL Server Data Access Components

package into two packages, one of which will be used as run-time only, and the other as
design-time only.
For the same reason, if your design-time packages require that certain DLLs be loaded, you
should remember that design-time packages can be only 32-bit and that is why they can load
only 32-bit versions of these DLLs, while at run-time 64-bit versions of the DLLs will be
loaded. Correspondingly, if there are only 64-bit versions of the DLL on your computer, you
won't be able to use all functions at design-time and, vice versa, if you have only 32-bit
versions of the DLLs, your application won't be able to work at run-time.
Extended type
For this type in a 64-bit applications compiler generates SSE2 instructions instead of FPU,
and that greatly improves performance in applications that use this type a lot (where data
accuracy is needed). For this purpose, the size and precision of Extended type is reduced:

TYPE
Extended

32-bit10 bytes

64-bit
8 bytes

The following two additional types are introduced to ensure compatibility in the process ofdeveloping 32- and 64-bit applications:
Extended80 – whose size in 32-bit application is 10 bytes; however, this type provides thesame precision as its 8-byte equivalent in 64-bit applications.
Extended80Rec – can be used to perform low-level operations on an extended precision
floating-point value. For example, the sign, the exponent, and the mantissa can be changed
separately. It enables you to perform memory-related operations with 10-bit floating-point
variables, but not extended-precision arithmetic operations.
Pointer and Integers
The major difference between 32- and 64-bit platforms is the volume of the used memory
and, correspondingly, the size of the pointer that is used to address large memory volumes.

TYPE
Pointer

32-bit
4 bytes64-bit
8 bytesAt the same time, the size of the Integer type remains the same for both platforms:

TYPE
Integer

32-bit
4 bytes64-bit
4 bytesThat is why, the following code will work incorrectly on the 64-bit platform:
Ptr := Pointer(Integer(Ptr) + Offset);
While this code will correctly on the 64-bit platform and incorrectly on the 32-bit platform:© 2019 Devart

Using SDAC141

Ptr := Pointer(Int64(Ptr) + Offset);
For this purpose, the following platform-dependent integer type is introduced:

TYPE
NativeInt
NativeUInt

32-bit
4 bytes
4 bytes64-bit
8 bytes
8 bytesThis type helps ensure that pointers work correctly both for the 32- and 64-bit platforms:
Ptr := Pointer(NativeInt(Ptr) + Offset);
However, you need to be extra-careful when developing applications for several versions ofDelphi, in which case you should remember that in the previous versions of Delphi the
NativeInt type had different sizes:

TYPE
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt
NativeInt

Delphi
Version
D5
D6
D7
D2005
D2006
D2007
D2009
D2010
Delphi XE
Delphi XE2

Size
N/A
N/A
8 bytes
8 bytes
8 bytes
8 bytes
4 bytes
4 bytes
4 bytes
4 or 8 bytes

Out parameters
Some WinAPIs have OUT parameters of the SIZE_T type, which is equivalent to NativeInt inDelphi XE2. The problem is that if you are developing only a 32-bit application, you won't beable to pass Integer to OUT, while in a 64-bit application, you will not be able to pass Int64; inboth cases you will have to pass NativeInt.
For example:
procedure MyProc(out Value: NativeInt);
begin
Value := 12345;
end;var
Value1: NativeInt;{$IFDEF WIN32}
Value2: Integer;{$ENDIF}{$IFDEF WIN64}© 2019 Devart

142

SQL Server Data Access Components

Value2: Int64;{$ENDIF}
begin
MyProc(Value1); // will be compiled;
MyProc(Value2); // will not be compiled !!!
end;
Win API
If you pass pointers to SendMessage/PostMessage/TControl.Perform, the wParam andlParam parameters should be type-casted to the WPARAM/LPARAM type and not to Integer/
Longint.
Correct:
SendMessage(hWnd, WM_SETTEXT, 0, LPARAM(@MyCharArray));
Wrong:
SendMessage(hWnd, WM_SETTEXT, 0, Integer(@MyCharArray));
Replace SetWindowLong/GetWindowLog with SetWindowLongPtr/GetWindowLongPtr for
GWLP_HINSTANCE, GWLP_ID, GWLP_USERDATA, GWLP_HWNDPARENT and
GWLP_WNDPROC as they return pointers and handles. Pointers that are passed to
SetWindowLongPtr should be type-casted to LONG_PTR and not to Integer/Longint.
Correct:
SetWindowLongPtr(hWnd, GWLP_WNDPROC, LONG_PTR(@MyWindowProc));
Wrong:
SetWindowLong(hWnd, GWL_WNDPROC, Longint(@MyWindowProc));
Pointers that are assigned to the TMessage.Result field should use a type-cast to LRESULT
instead of Integer/Longint.
Correct:
Message.Result := LRESULT(Self);Wrong:
Message.Result := Integer(Self);
All TWM...-records for the windows message handlers must use the correct Windows types
for the fields:
Msg: UINT; wParam: WPARAM; lParam: LPARAM; Result: LRESULT)
Assembler
In order to make your application (that uses assembly code) work, you will have to makeseveral changes to it:
rewrite your code that mixes Pascal code and assembly code. Mixing them is not supported
in 64-bit applications;rewrite assembly code that doesn't consider architecture and processor specifics.

© 2019 Devart

Using SDAC

143

You can use conditional defines to make your application work with different architectures.
You can learn more about Assembly code here: http://docwiki.embarcadero.com/RADStudio/
en/Using_Inline_Assembly_Code You can also look at the following article that will help you tomake your application support the 64-bit platform: http://docwiki.embarcadero.com/
RADStudio/en/Converting_32-bit_Delphi_Applications_to_64-bit_Windows
Exception handling
The biggest difference in exception handling between Delphi 32 and 64-bit is that in Delphi
XE2 64-bit you will gain more performance because of different internal exception
mechanism. For 32-bit applications, the Delphi compiler (dcc32.exe) generates additional
code that is executed any way and that causes performance loss. The 64-bit compiler(dcc64.exe) doesn't generate such code, it generates metadata and stores it in the PDATA
section of an executable file instead.
But in Delphi XE2 64-bit it's impossible to have more than 16 levels of nested exceptions.
Having more than 16 levels of nested exceptions will cause a Run Time error.
Debugging
Debugging of 64-bit applications in RAD Studio XE2 is remote. It is caused by the same
reason: RAD Studio XE2 IDE is a 32 application, but your application is 64-bit. If you are trying
to debug your application and you cannot do it, you should check that the Include remotedebug symbols project option is enabled.
To enable it, perform the following steps:
1. Open Project Options (in the main menu Project->Options).
2. In the Target combobox, select Debug configuration - 64-bit Windows platform. If there
is no such option in the combobox, right click "Target Platforms" in Project Manager andselect Add platform. After adding the 64-bit Windows platform, the Debug configuration 64-bit Windows platform option will be available in the Target combobox.
3. Select Linking in the left part of the Project Options form.
4. enable the Include remote debug symbols option.
After that, you can run and debug your 64-bit application.
To enable remote debugging, perform the following steps:
1. Install Platform Assistant Server (PAServer) on a remote computer. You can find PAServerin the %RAD_Studio_XE2_Install_Directory%\PAServer directory. The setup_paserver.exe
file is an installation file for Windows, and the setup_paserver.zip file is an istallation file for
MacOS.
2. Run the PAServer.exe file on a remote computer and set the password that will be used toconnect to this computer.
3. On a local computer with RAD Studio XE2 installed, right-click the target platform that you
want to debug in Project Manager and select Assign Remote Profile. Click the Add button© 2019 Devart

144

SQL Server Data Access Components

in the displayed window, input your profile name, click the Next button, input the name of aremote computer and the password to it (that you assigned when you started PAServer ona remote computer).
After that, you can test the connection by clicking the Test Connection button. If yourconnection failed, check that your firewalls on both remote and local computers do not block
your connection, and try to establish a connection once more. If your connection succeeded,click the Next button and then the Finish button. Select your newly created profile and clickOK.
After performing these steps you will be able to debug your application on a remote computer.
You application will be executed on a remote computer, but you will be able to debug it on
your local computer with RAD Studio XE2.
For more information about working with Platform Assistant Server, please refer to http://docwiki.embarcadero.com/RADStudio/Tokyo/en/
Running_the_Platform_Assistant_on_Windows© 1997-2019
Devart. All Rights
Reserved.

4.22

Request Support

DAC Forum

Provide Feedback

Integration with dbForge Studio for SQL Server
SDAC supports working with dbForge Studio for SQL Server. dbForge Studio for SQL Serveris a powerful SQL Server database development environment.
This tutorial explains the integration between SDAC and dbForge Studio for SQL Server.

Compatibility
SDAC supports dbForge Studio for SQL Server in almost all Delphi and C++Builder versions
except the following: Delphi 2006, C++Builder 2006, Delphi 2005.

Choosing integration
It is possible to choose what tool will be used by SDAC. Moreover, it is possible to disable
integration with any tool whatsoever. It can be done in the Delphi main menu->SDAC>Database Tools menu. There you can choose one of the three options (two options for IDE
versions earlier than RAD Studio 2007):

OptionMeaningdbForge Studio for
SQL Server
Integration

All the functionality described below uses
dbForge Studio for SQL Server© 2019 Devart

Using SDAC

No Integration

145

All functionality described below is
disabled and cannot be used

Using dbForge Studio for SQL Server in thecomponents
When dbForge Studio for SQL Server integration is enabled, several SDAC components
obtain additional functionality.
Note: Using any submenus of the "dbForge Studio for SQL Server" popup menu described
below opens dbForge Studio for SQL Server (if it was not opened before).

TMSConnection
The TMSConnection component obtains an additional popup menu (available by right-click on
the component) named "dbForge Studio for SQL Server". This menu contains the "Find in
Database Explorer" submenu. Clicking this submenu will cause the following steps to be
performed by SDAC and dbForge Studio for SQL Server:
If TMSConnection.ConnectString is blank, the "Connection is not defined" error isgenerated.
If TMSConnection.ConnectString is not blank, SDAC sends the message to dbForge Studiofor SQL Server to find in its Database Explorer the connection with the same connection
parameters as TMSConnection has. Note that if dbForge Studio for SQL Server was notrunning until this moment, it starts running.
If dbForge Studio for SQL Server found the appropriate connection in its Database Explorer,
it will make this connection the current connection and open it. Otherwise, dbForge Studiofor SQL Server will show the window with the following content:
There is no suitable connection found in Database Explorer. Do you want to create one?
It is up to you to decide whether you want or not to create a new connection in Database
Explorer of dbForge Studio for SQL Server.
Also, the TMSConnection editor form obtains a dropdown list that is filled with connections
from Database Explorer of dbForge Studio for SQL Server. When the value from this list is
chosen, TMSConnection's options are filled with the options obtained from dbForge Studio for
SQL Server.
Note: The dropdown list on the TMSConnection editor form is filled only if dbForge Studio for
SQL Server was running before the editor was opened.

TMSQuery and TSmartQuery© 2019 Devart

146

SQL Server Data Access Components

The TMSQuery and TSmartQuery components obtain an additional popup menu (available byright-click on the component) named "dbForge Studio for SQL Server". This menu contains
the following submenus:"Edit SQL" - clicking this submenu opens the new SQL editor in dbForge Studio for SQL
Server. Saving changes made in this editor saves them to the linked TMSQuery or
TSmartQuery component.
"Query Builder" - clicking this submenu opens the new Query Builder editor in dbForge
Studio for SQL Server.
"Step Into" - clicking this submenu starts debuging of a query in dbForge Studio for SQL
Server.
"Retrieve data" - clicking this submenu opens a query in dbForge Studio for SQL Server. If
the query contains the SELECT statement, the data is retrieved. Otherwise, the query is
executed.
Also, opening the TMSQuery and TSmartQuery editor form opens dbForge Studio for SQL
Server (if it was not opened before). This allows using powerful SQL editor of dbForge Studiofor SQL Server directly in the IDE.

TMSTable
The TMSTable component obtains an additional popup menu (available by right-click on thecomponent) named "dbForge Studio for SQL Server". This menu contains the following
submenus:"Find in Database Explorer" - clicking this submenu looks for the table specified in
TMSTable.TableName in Database Explorer of dbForge Studio for SQL Server. If the table
is found, it is made current.
"Edit Object" - clicking this submenu opens the table editor in dbForge Studio for SQL
Server. In the editor, it is possible to modify the structure of the table, its indexes, etc.

TMSStoredProc
The TMSStoredProc component obtains an additional popup menu (available by right-click on
the component) named "dbForge Studio for SQL Server". This menu contains the following
submenus:"Find in Database Explorer" - clicking this submenu looks for the stored procedure specified
in TMSStoredProc.StoredProcName in Database Explorer of dbForge Studio for SQL
Server. If the stored procedure is found, it is made the current.
"Step Into" - clicking this submenu starts debuging of a stored procedure in dbForge Studiofor SQL Server.

© 2019 Devart

Using SDAC

147

"Recompile" - clicking this submenu recompiles a stored procedure in dbForge Studio for
SQL Server.
"Recompile with debug info" - clicking this submenu recompiles a stored procedure withdebug info in dbForge Studio for SQL Server.
Also, opening the TMSStoredProc editor form opens dbForge Studio for SQL Server (if it was
not opened before). This allows using powerful SQL editor of dbForge Studio for SQL Server
directly in the IDE.

TMSSQLThe TMSSQL component obtains an additional popup menu (available by right-click on thecomponent) named "dbForge Studio for SQL Server". This menu contains the following
submenus:"Edit SQL" - clicking this submenu opens the new SQL editor in dbForge Studio for SQL
Server. Saving changes made in this editor saves them to the linked TMSSQL component.
"Step Into" - clicking this submenu starts debuging of a query in dbForge Studio for SQL
Server.
Also, opening the TMSSQL editor form opens dbForge Studio for SQL Server (if it was not
opened before). This allows using powerful SQL editor of dbForge Studio for SQL Server
directly in the IDE.

TMSScript
The TMSScript component obtains an additional popup menu (available by right-click on thecomponent) named "dbForge Studio for SQL Server". This menu contains the following
submenus:"Edit SQL" - clicking this submenu opens the new SQL editor in dbForge Studio for SQL
Server. Saving changes made in this editor saves them to the linked TMSScript component.
"Step Into" - clicking this submenu starts debuging of a script in dbForge Studio for SQL
Server.
Also, opening the TMSScript editor form opens dbForge Studio for SQL Server (if it was not
opened before). This allows using powerful SQL editor of dbForge Studio for SQL Server
directly in the IDE.

TMSPackage
The TMSPackage component obtains an additional popup menu (available by right-click on
the component) named "dbForge Studio for SQL Server". This menu contains the following
submenus:© 2019 Devart

148

SQL Server Data Access Components"Find in Database Explorer" - clicking this submenu looks for the package specified in
TMSPackage.PackageName in Database Explorer of dbForge Studio for SQL Server. If the
package is found, it is made the current.
"Edit Object" - clicking this submenu opens the package editor in dbForge Studio for SQL
Server. In the editor, it is possible to modify the content of the package.

© 1997-2019
Devart. All Rights
Reserved.

4.23

Request Support

DAC Forum

Provide Feedback

Database Specific Aspects of 64-bit Development

SQL Server Connectivity Aspects
If you are working in the Direct mode or developing a 32-bit application only, then thedevelopment process will not be different for you, except some peculiarities of each particular
platform. But if you are developing a 64-bit application, you have to be aware of specifics ofworking with client libraries at design-time and run-time. To connect to a SQL Server
database at design-time, you must have its 32-bit client library. You have to place it to the C:\Windows\SysWOW64 directory. This requirement flows out from the fact that RAD Studio
XE2 is a 32-bit application and it cannot load 64-bit libraries at design-time. To work with a
SQL Server database at run-time (64-bit application), you must have the 64-bit client libraryplaced to the C:\Windows\System32 directory.

© 1997-2019
Devart. All Rights
Reserved.

4.24

Request Support

DAC Forum

Provide Feedback

FILESTREAM DataFILESTREAM is a feature of SQL Server 2008, which allows storage of and efficient accessto BLOB data using a combination of SQL Server 2008 and the NTFS file system.
This topic demonstrates how to work with FILESTREAM data with the help of SDAC.
To work with FILESTREAM data, you should have an appropriate table on a server. SQL
Server requires a table to have a column of the UNIQUEIDENTIFIER data type that has the
ROWGUIDCOL attribute to be an appropriate one for working with FILESTREAM data. This
column must not allow NULL values and must have either a UNIQUE or PRIMARY KEY
single-column constraint. A FILESTREAM column must be defined as a VARBINARY(MAX)column that has the FILESTREAM attribute.
Here is an example of a script to create a correct table:
CREATE TABLE TESTFS(
ID INT PRIMARY KEY NOT NULL,FS VARBINARY(MAX) FILESTREAM NULL,© 2019 Devart

Using SDAC

149

GD UNIQUEIDENTIFIER UNIQUE ROWGUIDCOL NOT NULL DEFAULT NEWID())
The FILESTREAM data is represented by a file on a computer where SQL Server is installed.
In order to start working with it, you should insert any value into your FILESTREAM column.
This will create a new file on a server and it will be possible to work with it. Here is an example
that demonstrates it:
Delphi:MSQuery.SQL.Text := 'SELECT * FROM TESTFS';
MSQuery.Open;MSQuery.Append;
MSQuery.FieldByName('ID').AsInteger := 1;
MSQuery.FieldByName('FS').AsString := 'TEST';MSQuery.Post;
C++Builder:
MSQuery->SQL->Text = "SELECT * FROM TESTFS";
MSQuery->Open();
MSQuery->Append();
MSQuery->FieldByName("ID")->AsInteger = 1;
MSQuery->FieldByName("FS")->AsString = "TEST";MSQuery->Post();After the steps above have been performed, it is possible to work with FILESTREAM data.
Here is an example that demonstrates it:
Delphi:procedure TMainForm.BitBtnRunClick(Sender: TObject);var
con: TMSConnection;
qr: TMSQuery;
fs: TMSFileStream;ts: AnsiString;
begin
con := TMSConnection.Create(nil);
qr := TMSQuery.Create(nil);try
con.Authentication := auWindows; // FILESTREAM requirement
con.Server := 'server';con.Database := 'database';
qr.Connection := con;
qr.SQL.Text := 'SELECT * FROM TESTFS';
qr.Open;//writing data
con.StartTransaction; // FILESTREAM requirement
fs := qr.GetFileStreamForField('FS', daWrite);ts := 'TEST FILESTREAM';
fs.WriteBuffer(ts[1], Length(ts));
fs.Flush;
fs.Close; // it's necessary to call this method before the transaction ccon.Commit;//reading data
con.StartTransaction; // FILESTREAM requirement© 2019 Devart

150

SQL Server Data Access Components

fs := qr.GetFileStreamForField('FS', daRead);
SetLength(ts, fs.Size);
fs.ReadBuffer(ts[1], fs.Size);
ShowMessage(ts);fs.Close; // it's necessary to call this method before the transaction ccon.Commit;
finally
qr.Free;con.Free;end;
end;
C++Builder:

void __fastcall TMainForm::BitBtnRunClick(TObject *Sender){
TMSConnection* con = new TMSConnection(NULL);TMSQuery* qr = new TMSQuery(NULL);
try{
con->Authentication = auWindows; // FILESTREAM requirement
con->Server = "server";con->Database = "database";
qr->Connection = con;
qr->SQL->Text = "SELECT * FROM TESTFS";
qr->Open();//writing data
con->StartTransaction(); // FILESTREAM requirement
TMSFileStream* fs = qr->GetFileStreamForField("FS", daWrite);char* ts = "TEST FILESTREAM";
fs->WriteBuffer(ts, strlen(ts));
fs->Flush();fs->Close(); // it's necessary to call this method before the transactio
con->Commit();//reading data
con->StartTransaction(); // FILESTREAM requirement
fs = qr->GetFileStreamForField("FS", daRead);ts = new char[fs->Size];
fs->ReadBuffer(ts, fs->Size);
ShowMessage(ts);fs->Close(); // it's necessary to call this method before the transactio
con->Commit();}__finally{
qr->Free();con->Free();}}As you can see from these examples, you don't need to free TMSFileStream manually. SDAC
takes care of freeing all assigned TMSFileStream objects.
Note: You can find more information about working with FILESTREAM data in MSDN at http://
msdn.microsoft.com/en-us/library/cc949109(v=sql.100).aspx© 2019 Devart

Using SDAC

151

See also
GetFileStreamForField
Close
Flush

© 1997-2019
Devart. All Rights
Reserved.

5

Request Support

DAC Forum

Provide Feedback

Reference
This page shortly describes units that exist in SDAC.

Units
Unit Name
CRAccess

CRBatchMove
CREncryption
CRVio
DAAlerter

DADump

DALoaderDAScriptDASQLMonitor
DBAccess© 2019 Devart

Description
This unit contains baseclasses for accessing
databases.
This unit contains
implementation of the
TCRBatchMove component.
This unit contains baseclasses for data encryption.
Description is not available
at the moment.
This unit contains the baseclass for the TMSAlerter
component.
This unit contains the baseclass for the TMSDumpcomponent.
This unit contains the baseclass for the TMSLoader
component.
This unit contains the baseclass for the TMSScript
component.
This unit contains the baseclass for the
TMSSQLMonitor
component.
This unit contains base152

SQL Server Data Access Components

Devart.Dac.DataAdapter

Devart.Sdac.DataAdapter
MemData
MemDS

MSAccess

MSClasses

MSCompactConnection

MSConnectionPool

MSDump

MSLoaderMSScript

MSServiceBroker

MSSQLMonitor

classes for most of thecomponents.
This unit contains
implementation of the
DADataAdapter class.
This unit contains
implementation of the
MSDataAdapter class.
This unit contains classes forstoring data in memory.
This unit contains
implementation of the
TMemDataSet class.
This unit contains
implementation of mostpublic classes of SDAC.
This unit contains
implementation of SQL
Server classes.
This unit contains
implementation of the
TMSCompactConnection
class.
This unit contains the
TMSConnectionPoolManager class for managing
connection pool.
This unit contains
implementation of the
TMSDump component.
This unit contains
implementation of the
TMSLoader component.
This unit contains
implementation of the
TMSScript component.
This unit contains
implementation of the
TMSServiceBroker
component and auxiliary
classes.
This unit contains
implementation of theTMSSQLMonitor© 2019 DevartReferencecomponent.
This unit contains
implementation of theTMSTransaction
component.
This unit contains classes foraccessing SQL Server
through OLE DB providers
This unit contains the visual
constituent of SDAC.
This unit contains
implementation of theTVirtualDataSet component.
This unit contains
implementation of theTVirtualTable component.

MSTransaction

OLEDBAccess
SdacVclVirtualDataSet

VirtualTable© 1997-2019
Devart. All Rights
Reserved.

5.1

153

Request Support

DAC Forum

Provide Feedback

CRAccess
This unit contains base classes for accessing databases.

Classes
Name
TCRCursor

Description
A base class for classes thatwork with database cursors.

Types
Name
TBeforeFetchProc

Description
This type is used for the
TCustomDADataSet.Before
Fetch event.

Enumerations
Name
TCRIsolationLevel© 2019 Devart

Description
Specifies how to handle
transactions containing
database modifications.

154

SQL Server Data Access Components

Specifies the transaction
behaviour when it isdestroyed while being
active, or when one of its
connections is closed withthe active transaction.
Used to set cursor state

TCRTransactionAction

TCursorState© 1997-2019
Devart. All Rights
Reserved.
5.1.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the CRAccess unit.

ClassesName

Description
A base class for classes thatwork with database cursors.

TCRCursor© 1997-2019
Devart. All Rights
Reserved.
5.1.1.1

Request Support

DAC Forum

Provide Feedback

TCRCursor ClassA base class for classes that work with database cursors.
For a list of all members of this type, see TCRCursor members.

Unit
CRAccess

Syntax
TCRCursor = class(TSharedObject);Remarks
TCRCursor is a base class for classes that work with database cursors.

Inheritance Hierarchy
TSharedObject
TCRCursor© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

155

Provide Feedback

5.1.1.1.1 Members

TCRCursor class overview.

Properties
Name

Description
Used to return the count ofreference to a
TSharedObject object.

RefCount (inherited from TSharedObject)

Methods
Name

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Decrements the reference
count.

AddRef (inherited from TSharedObject)

Release (inherited from TSharedObject)© 1997-2019
Devart. All Rights
Reserved.
5.1.2

Request Support

DAC Forum

Provide Feedback

Types
Types in the CRAccess unit.

Types
Name

Description
This type is used for the
TCustomDADataSet.Before
Fetch event.

TBeforeFetchProc© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

156

SQL Server Data Access Components

5.1.2.1

TBeforeFetchProc Procedure ReferenceThis type is used for the TCustomDADataSet.BeforeFetch event.

Unit
CRAccess

SyntaxTBeforeFetchProc = procedure (var Cancel: boolean) of object;Parameters
CancelTrue, if the current fetch operation should be aborted.

© 1997-2019
Devart. All Rights
Reserved.
5.1.3

Request Support

DAC Forum

Provide Feedback

Enumerations
Enumerations in the CRAccess unit.

Enumerations
Name

Description
Specifies how to handle
transactions containing
database modifications.
Specifies the transaction
behaviour when it isdestroyed while being
active, or when one of its
connections is closed withthe active transaction.
Used to set cursor state

TCRIsolationLevel

TCRTransactionAction

TCursorState© 1997-2019
Devart. All Rights
Reserved.
5.1.3.1

Request Support

DAC Forum

Provide Feedback

TCRIsolationLevel Enumeration

Specifies how to handle transactions containing database modifications.

Unit© 2019 DevartReference

157

CRAccess

SyntaxTCRIsolationLevel = (ilReadCommitted);

ValuesValue
ilReadCommitted© 1997-2019
Devart. All Rights
Reserved.
5.1.3.2

Meaning
The default transaction behavior. If the transaction contains DML
that requires row locks held by another transaction, then the DML
statement waits until the row locks are released.
Request Support

DAC Forum

Provide Feedback

TCRTransactionAction Enumeration

Specifies the transaction behaviour when it is destroyed while being active, or when one of its
connections is closed with the active transaction.

Unit
CRAccess

SyntaxTCRTransactionAction = (taCommit, taRollback);

ValuesValue
taCommit
taRollback© 1997-2019
Devart. All Rights
Reserved.
5.1.3.3

Meaning
Transaction is committed.
Transaction is rolled back.
Request Support

TCursorState Enumeration

Used to set cursor state

Unit
CRAccess© 2019 Devart

DAC Forum

Provide Feedback

158

SQL Server Data Access Components

SyntaxTCursorState = (csInactive, csOpen, csParsed, csPrepared, csBound,csExecuteFetchAll, csExecuting, csExecuted, csFetching,csFetchingAll, csFetched);

ValuesValue
Meaning
csBoundParameters boundcsExecuted
Statement successfully executed
csExecuteFetchAll Set before FetchAll
csExecuting
Statement is set before executing
csFetched
Fetch finished or canceled
csFetching
Set on firstcsFetchingAll
Set on the FetchAll startcsInactive
Default state
csOpenstatement open
csParsed
Statement parsed
csPrepared
Statement prepared© 1997-2019
Request Support
DAC Forum
Devart. All Rights
Reserved.

5.2

Provide Feedback

CRBatchMove
This unit contains implementation of the TCRBatchMove component.

ClassesName
TCRBatchMove

Description
Transfers records between
datasets.

Types
Name
TCRBatchMoveProgressEvent

Description
This type is used for the
TCRBatchMove.OnBatchMo
veProgress event.

© 2019 DevartReference

159

Enumerations
Name

Description
Used to set the type of thebatch operation that will be
executed after calling the
TCRBatchMove.Execute
method.
Used to specify the way
fields of the destination andsource datasets will bemapped to each other if the
TCRBatchMove.Mappings
list is empty.

TCRBatchMode

TCRFieldMappingMode© 1997-2019
Devart. All Rights
Reserved.
5.2.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the CRBatchMove unit.

ClassesName

Description
Transfers records between
datasets.

TCRBatchMove© 1997-2019
Devart. All Rights
Reserved.
5.2.1.1

Request Support

DAC Forum

TCRBatchMove Class

Transfers records between datasets.
For a list of all members of this type, see TCRBatchMove members.

Unit
CRBatchMove

SyntaxTCRBatchMove = class(TComponent);© 2019 Devart

Provide Feedback

160

SQL Server Data Access Components

Remarks
The TCRBatchMove component transfers records between datasets. Use it to copy dataset
records to another dataset or to delete datasets records that match records in anotherdataset. The TCRBatchMove.Mode property determines the desired operation type, the
TCRBatchMove.Source and TCRBatchMove.Destination properties indicate corresponding
datasets.
Note: A TCRBatchMove component is added to the Data Access page of the component
palette, not to the SDAC page.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.1 Members

TCRBatchMove class overview.

Properties
Name
AbortOnKeyViol

AbortOnProblem

ChangedCount

CommitCount

Destination

FieldMappingMode

Description
Used to specify whether thebatch operation should beterminated immediately after
key or integrity violation.
Used to specify whether thebatch operation should beterminated immediately
when it is necessary to
truncate data to make it fit
the specified Destination.
Used to get the number ofrecords changed in thedestination dataset.
Used to set the number ofrecords to be batch moved
before commit occurs.
Used to specify thedestination dataset for thebatch operation.
Used to specify the way
fields of destination andsource datasets will bemapped to each other if the
TCRBatchMove.Mappings© 2019 DevartReference

KeyViolCount

Mappings

Mode

MovedCount

ProblemCount

RecordCount

Sourcelist is empty.
Used to get the number ofrecords that could not be
moved to or from thedestination dataset because
of integrity or key violations.
Used to set field matching
between source anddestination datasets for thebatch operation.
Used to set the type of thebatch operation that will be
executed after calling the
TCRBatchMove.Execute
method.
Used to get the number ofrecords that were read fromthe source dataset during
the batch operation.
Used to get the number ofrecords that could not be
added to the destination
dataset because of the field
type mismatch.
Used to indicate themaximum number of records
in the source dataset that will
be applied to the destination
dataset.
Used to specify the source
dataset for the batch
operation.

Methods
Name
ExecuteDescription
Performs the batch
operation.

EventsName
OnBatchMoveProgress© 2019 Devart

161

Description
Occurs when providing

162

SQL Server Data Access Components

feedback to the user about
the batch operation inprogress is needed.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2 Properties

Properties of the TCRBatchMove class.
For a complete list of the TCRBatchMove class members, see the TCRBatchMove
Members topic.

PublicName
ChangedCount

KeyViolCount

MovedCount

ProblemCount

Description
Used to get the number ofrecords changed in thedestination dataset.
Used to get the number ofrecords that could not be
moved to or from thedestination dataset because
of integrity or key violations.
Used to get the number ofrecords that were read fromthe source dataset during
the batch operation.
Used to get the number ofrecords that could not be
added to the destination
dataset because of the field
type mismatch.

Published
Name
AbortOnKeyViol

Description
Used to specify whether thebatch operation should beterminated immediately after
key or integrity violation.

AbortOnProblem

Used to specify whether thebatch operation should be© 2019 DevartReference163

terminated immediately
when it is necessary to
truncate data to make it fit
the specified Destination.
Used to set the number ofrecords to be batch moved
before commit occurs.
Used to specify thedestination dataset for thebatch operation.
Used to specify the way
fields of destination andsource datasets will bemapped to each other if the
TCRBatchMove.Mappings
list is empty.
Used to set field matching
between source anddestination datasets for thebatch operation.
Used to set the type of thebatch operation that will be
executed after calling the
TCRBatchMove.Execute
method.
Used to indicate themaximum number of records
in the source dataset that will
be applied to the destination
dataset.
Used to specify the source
dataset for the batch
operation.

CommitCount

Destination

FieldMappingMode

Mappings

Mode

RecordCount

SourceSee Also
TCRBatchMove ClassTCRBatchMove Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

164

SQL Server Data Access Components

5.2.1.1.2.1 AbortOnKeyViol Property

Used to specify whether the batch operation should be terminated immediately after key or
integrity violation.

Class
TCRBatchMove

Syntaxproperty AbortOnKeyViol: boolean default True;

Remarks
Use the AbortOnKeyViol property to specify whether the batch operation is terminatedimmediately after key or integrity violation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.2 AbortOnProblem Property

Used to specify whether the batch operation should be terminated immediately when it isnecessary to truncate data to make it fit the specified Destination.

Class
TCRBatchMove

Syntaxproperty AbortOnProblem: boolean default True;

Remarks
Use the AbortOnProblem property to specify whether the batch operation is terminatedimmediately when it is necessary to truncate data to make it fit the specified Destination.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.3 ChangedCount Property

Used to get the number of records changed in the destination dataset.

Class© 2019 DevartReference

165

TCRBatchMove

Syntaxproperty ChangedCount: Integer;

Remarks
Use the ChangedCount property to get the number of records changed in the destination
dataset. It shows the number of records that were updated in the bmUpdate or
bmAppendUpdate mode or were deleted in the bmDelete mode.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.4 CommitCount Property

Used to set the number of records to be batch moved before commit occurs.

Class
TCRBatchMove

Syntaxproperty CommitCount: integer default 0;

Remarks
Use the CommitCount property to set the number of records to be batch moved before thecommit occurs. If it is set to 0, the operation will be chunked to the number of records to fit 32
Kb.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.2.1.1.2.5 Destination Property

Used to specify the destination dataset for the batch operation.

Class
TCRBatchMove

Syntaxproperty Destination: TDataSet;© 2019 Devart

Provide Feedback

166

SQL Server Data Access Components

Remarks
Specifies the destination dataset for the batch operation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.6 FieldMappingMode Property

Used to specify the way fields of destination and source datasets will be mapped to eachother if the Mappings list is empty.

Class
TCRBatchMove

Syntaxproperty FieldMappingMode: TCRFieldMappingMode default
mmFieldIndex;

Remarks
Specifies in what way fields of destination and source datasets will be mapped to each otherif the Mappings list is empty.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.7 KeyViolCount Property

Used to get the number of records that could not be moved to or from the destination dataset
because of integrity or key violations.

Class
TCRBatchMove

Syntaxproperty KeyViolCount: Integer;

Remarks
Use the KeyViolCount property to get the number of records that could not be replaced,added, deleted from the destination dataset because of integrity or key violations.

© 2019 DevartReference167

If AbortOnKeyViol is True, then KeyViolCount will never exceed one, because the operationaborts when the integrity or key violation occurs.

See Also
AbortOnKeyViol© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.8 Mappings Property

Used to set field matching between source and destination datasets for the batch operation.

Class
TCRBatchMove

Syntaxproperty Mappings: TStrings;

Remarks
Use the Mappings property to set field matching between the source and destination datasets
for the batch operation. By default fields matching is based on their position in the datasets.
To map the column ColName in the source dataset to the column with the same name in thedestination dataset, use:
ColNameExampleTo map a column named SourceColName in the source dataset to the column named
DestColName in the destination dataset, use:
DestColName=SourceColName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.9 Mode Property

Used to set the type of the batch operation that will be executed after calling the Execute
method.

Class© 2019 Devart

168

SQL Server Data Access Components

TCRBatchMove

Syntaxproperty Mode: TCRBatchMode default bmAppend;

Remarks
Use the Mode property to set the type of the batch operation that will be executed after calling
the Execute method.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.10 MovedCount Property

Used to get the number of records that were read from the source dataset during the batch
operation.

Class
TCRBatchMove

Syntaxproperty MovedCount: Integer;

Remarks
Use the MovedCount property to get the number of records that were read from the source
dataset during the batch operation. This number includes records that caused key or integrity
violations or were trimmed.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.11 ProblemCount Property

Used to get the number of records that could not be added to the destination dataset becauseof the field type mismatch.

Class
TCRBatchMove

Syntax© 2019 DevartReference

169

property ProblemCount: Integer;

Remarks
Use the ProblemCount property to get the number of records that could not be added to thedestination dataset because of the field type mismatch.
If AbortOnProblem is True, then ProblemCount will never exceed one, because the operationaborts when the problem occurs.

See Also
AbortOnProblem© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.2.12 RecordCount Property

Used to indicate the maximum number of records in the source dataset that will be applied tothe destination dataset.

Class
TCRBatchMove

Syntaxproperty RecordCount: Integer default 0;

Remarks
Determines the maximum number of records in the source dataset, that will be applied to thedestination dataset. If it is set to 0, all records in the source dataset will be applied to thedestination dataset, starting from the first record. If RecordCount is greater than 0, up to the
RecordCount records are applied to the destination dataset, starting from the current recordin the source dataset. If RecordCount exceeds the number of records left in the source
dataset, batch operation terminates after reaching last record.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.2.1.1.2.13 Source Property

Used to specify the source dataset for the batch operation.

Class© 2019 Devart

Provide Feedback

170

SQL Server Data Access Components

TCRBatchMove

Syntaxproperty Source: TDataSet;

Remarks
Specifies the source dataset for the batch operation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.3 Methods

Methods of the TCRBatchMove class.
For a complete list of the TCRBatchMove class members, see the TCRBatchMove
Members topic.

PublicName

Description
Performs the batch
operation.

ExecuteSee Also
TCRBatchMove ClassTCRBatchMove Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.3.1 Execute Method

Performs the batch operation.

Class
TCRBatchMove

Syntax
procedure Execute;

Remarks© 2019 DevartReference

171

Call the Execute method to perform the batch operation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.4 Events

Events of the TCRBatchMove class.
For a complete list of the TCRBatchMove class members, see the TCRBatchMove
Members topic.

Published
Name

Description
Occurs when providing
feedback to the user about
the batch operation inprogress is needed.

OnBatchMoveProgress

See Also
TCRBatchMove ClassTCRBatchMove Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.2.1.1.4.1 OnBatchMoveProgress Event

Occurs when providing feedback to the user about the batch operation in progress is needed.

Class
TCRBatchMove

Syntaxproperty OnBatchMoveProgress: TCRBatchMoveProgressEvent;Remarks
Write the OnBatchMoveProgress event handler to provide feedback to the user about thebatch operation progress.

© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

172

5.2.2

SQL Server Data Access Components

Types
Types in the CRBatchMove unit.

Types
Name

Description
This type is used for the
TCRBatchMove.OnBatchMo
veProgress event.

TCRBatchMoveProgressEvent© 1997-2019
Devart. All Rights
Reserved.
5.2.2.1

Request Support

DAC Forum

Provide Feedback

TCRBatchMoveProgressEvent Procedure ReferenceThis type is used for the TCRBatchMove.OnBatchMoveProgress event.

Unit
CRBatchMove

SyntaxTCRBatchMoveProgressEvent = procedure (Sender: TObject; Percent:integer) of object;Parameters
SenderAn object that raised the event.
Percent
Percentage of the batch operation progress.

© 1997-2019
Devart. All Rights
Reserved.
5.2.3

Request Support

DAC Forum

Provide Feedback

Enumerations
Enumerations in the CRBatchMove unit.

Enumerations
Name
TCRBatchMode

Description
Used to set the type of thebatch operation that will be
executed after calling the© 2019 DevartReference

TCRBatchMove.Execute
method.
Used to specify the way
fields of the destination andsource datasets will bemapped to each other if the
TCRBatchMove.Mappings
list is empty.

TCRFieldMappingMode© 1997-2019
Devart. All Rights
Reserved.
5.2.3.1

Request Support

173

DAC Forum

Provide Feedback

TCRBatchMode Enumeration

Used to set the type of the batch operation that will be executed after calling the
TCRBatchMove.Execute method.

Unit
CRBatchMove

SyntaxTCRBatchMode = (bmAppend, bmUpdate, bmAppendUpdate, bmDelete);

ValuesValue

Meaning
Appends the records from the source dataset to the destination
bmAppend
dataset. The default mode.
Replaces records in the destination dataset with the matching
bmAppendUpdate records from the source dataset. If there is no matching record in
the destination dataset, the record will be appended to it.
Deletes records from the destination dataset if there are
bmDeletematching records in the source dataset.
Replaces records in the destination dataset with the matching
bmUpdate
records from the source dataset.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
5.2.3.2

TCRFieldMappingMode Enumeration

Used to specify the way fields of the destination and source datasets will be mapped to eachother if the TCRBatchMove.Mappings list is empty.
© 2019 Devart

174

SQL Server Data Access Components

Unit
CRBatchMove

Syntax
TCRFieldMappingMode = (mmFieldIndex, mmFieldName);

ValuesValue
mmFieldIndex
mmFieldName© 1997-2019
Devart. All Rights
Reserved.

5.3

MeaningSpecifies that the fields of the destination dataset will be mapped
to the fields of the source dataset by field index.
Mapping is performed by field names.
Request Support

DAC Forum

Provide Feedback

CREncryption
This unit contains base classes for data encryption.

ClassesName
TCREncryptor

Description
The class that performs dataencryption and decryption ina client application using
various encryption
algorithms.

Enumerations
Name
TCREncDataHeader

TCREncryptionAlgorithm
TCRHashAlgorithm
TCRInvalidHashAction

Description
Specifies whether the
additional information isstored with the encrypteddata.
Specifies the algorithm ofdata encryption.
Specifies the algorithm ofgenerating hash data.
Specifies the action to© 2019 DevartReference

175

perform on data fetchingwhen hash data is invalid.
© 1997-2019
Devart. All Rights
Reserved.
5.3.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the CREncryption unit.

ClassesName

Description
The class that performs dataencryption and decryption ina client application using
various encryption
algorithms.

TCREncryptor© 1997-2019
Devart. All Rights
Reserved.
5.3.1.1

Request Support

DAC Forum

Provide Feedback

TCREncryptor Class

The class that performs data encryption and decryption in a client application using various
encryption algorithms.
For a list of all members of this type, see TCREncryptor members.

Unit
CREncryption

SyntaxTCREncryptor = class(TComponent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.3.1.1.1 Members

TCREncryptor class overview.

Properties© 2019 Devart

DAC Forum

Provide Feedback

176

SQL Server Data Access Components

Name

Description
Specifies whether the
additional information isstored with the encrypteddata.
Specifies the algorithm ofdata encryption.
Specifies the algorithm ofgenerating hash data.
Specifies the action to
perform on data fetchingwhen hash data is invalid.
Used to set a password thatis used to generate a key forencryption.

DataHeader

EncryptionAlgorithm
HashAlgorithm
InvalidHashAction

Password

Methods
Name

Description
Sets a key, using which datais encrypted.

SetKey© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2 Properties

Properties of the TCREncryptor class.
For a complete list of the TCREncryptor class members, see the TCREncryptor Members
topic.

Published
Name
DataHeader

EncryptionAlgorithm
HashAlgorithm
InvalidHashAction

Description
Specifies whether the
additional information isstored with the encrypteddata.
Specifies the algorithm ofdata encryption.
Specifies the algorithm ofgenerating hash data.
Specifies the action to© 2019 DevartReference

177

perform on data fetchingwhen hash data is invalid.
Used to set a password thatis used to generate a key forencryption.

Password

See Also
TCREncryptor ClassTCREncryptor Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2.1 DataHeader Property

Specifies whether the additional information is stored with the encrypted data.

Class
TCREncryptor

Syntaxproperty DataHeader: TCREncDataHeader default ehTagAndHash;

Remarks
Use DataHeader to specify whether the additional information is stored with the encrypted
data. Default value is ehTagAndHash.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2.2 EncryptionAlgorithm Property

Specifies the algorithm of data encryption.

Class
TCREncryptor

Syntaxproperty EncryptionAlgorithm: TCREncryptionAlgorithm default
eaBlowfish;© 2019 Devart

178

SQL Server Data Access Components

Remarks
Use EncryptionAlgorithm to specify the algorithm of data encryption. Default value is
eaBlowfish.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2.3 HashAlgorithm Property

Specifies the algorithm of generating hash data.

Class
TCREncryptor

Syntaxproperty HashAlgorithm: TCRHashAlgorithm default haSHA1;

Remarks
Use HashAlgorithm to specify the algorithm of generating hash data. This property is used
only if hash is stored with the encrypted data (the DataHeader property is set to
ehTagAndHash). Default value is haSHA1.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2.4 InvalidHashAction Property

Specifies the action to perform on data fetching when hash data is invalid.

Class
TCREncryptor

Syntaxproperty InvalidHashAction: TCRInvalidHashAction default ihFail;

Remarks
Use InvalidHashAction to specify the action to perform on data fetching when hash data isinvalid. This property is used only if hash is stored with the encrypted data (the DataHeader
property is set to ehTagAndHash). Default value is ihFail.

© 2019 DevartReference179

If the DataHeader property is set to ehTagAndHash, then on data fetching from a server thehash check is performed for each record. After data decryption its hash is calculated andcompared with the hash stored in the field. If these values don't coincide, it means that thestored data is incorrect, and depending on the value of the InvalidHashAction property one of
the following actions is performed:
ihFail - the EInvalidHash exception is raised and further data reading from the server isinterrupted.
ihSkipData - the value of the field for this record is set to Null. No exception is raised.
ihIgnoreError - in spite of the fact that the data is not valid, the value is set in the field. No
exception is raised.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.2.5 Passw ord Property

Used to set a password that is used to generate a key for encryption.

Class
TCREncryptor

Syntaxproperty Password: string stored False;

Remarks
Use Password to set a password that is used to generate a key for encryption.
Note: Calling of the SetKey method clears the Password property.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.3 Methods

Methods of the TCREncryptor class.
For a complete list of the TCREncryptor class members, see the TCREncryptor Members
topic.

Public
Name
SetKey© 2019 Devart

Description
Sets a key, using which data

180

SQL Server Data Access Components

is encrypted.

See Also
TCREncryptor ClassTCREncryptor Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.3.1.1.3.1 SetKey Method

Sets a key, using which data is encrypted.

Class
TCREncryptor

Syntax
procedure SetKey(const Key; Count: Integer); overload;procedure
SetKey(const Key: TBytes; Offset: Integer; Count: Integer);overload;
Parameters
Key
Holds bytes that represent a key.
OffsetOffset in bytes to the position, where the key begins.
Count
Number of bytes to use from Key.

Remarks
Use SetKey to set a key, using which data is encrypted.
Note: Calling of the SetKey method clears the Password property.

© 1997-2019
Devart. All Rights
Reserved.
5.3.2

Request Support

DAC Forum

Provide Feedback

Enumerations
Enumerations in the CREncryption unit.

Enumerations© 2019 DevartReference

Name

Description
Specifies whether the
additional information isstored with the encrypteddata.
Specifies the algorithm ofdata encryption.
Specifies the algorithm ofgenerating hash data.
Specifies the action to
perform on data fetchingwhen hash data is invalid.

TCREncDataHeader

TCREncryptionAlgorithm
TCRHashAlgorithm
TCRInvalidHashAction© 1997-2019
Devart. All Rights
Reserved.
5.3.2.1

Request Support

181

DAC Forum

Provide Feedback

TCREncDataHeader Enumeration

Specifies whether the additional information is stored with the encrypted data.

Unit
CREncryption

SyntaxTCREncDataHeader = (ehTagAndHash, ehTag, ehNone);

ValuesValue
ehNoneehTag
ehTagAndHash© 1997-2019
Devart. All Rights
Reserved.
5.3.2.2

Meaning
No additional information is stored.
GUID and the random initialization vector are stored with theencrypted data.
Hash, GUID, and the random initialization vector are stored withthe encrypted data.
Request Support

TCREncryptionAlgorithm Enumeration

Specifies the algorithm of data encryption.

Unit© 2019 Devart

DAC Forum

Provide Feedback

182

SQL Server Data Access Components

CREncryption

SyntaxTCREncryptionAlgorithm = (eaTripleDES, eaBlowfish, eaAES128,
eaAES192, eaAES256, eaCast128, eaRC4);

ValuesValue
eaAES128
eaAES192
eaAES256
eaBlowfish
eaCast128
eaRC4
eaTripleDES© 1997-2019
Devart. All Rights
Reserved.
5.3.2.3

Meaning
The AES encryption algorithm with key size of 128 bits is used.
The AES encryption algorithm with key size of 192 bits is used.
The AES encryption algorithm with key size of 256 bits is used.
The Blowfish encryption algorithm is used.
The CAST-128 encryption algorithm with key size of 128 bits is
used.
The RC4 encryption algorithm is used.
The Triple DES encryption algorithm is used.
Request Support

DAC Forum

Provide Feedback

TCRHashAlgorithm Enumeration

Specifies the algorithm of generating hash data.

Unit
CREncryption

SyntaxTCRHashAlgorithm = (haSHA1, haMD5);

ValuesValue
haMD5
haSHA1© 1997-2019
Devart. All Rights
Reserved.

Meaning
The MD5 hash algorithm is used.
The SHA-1 hash algorithm is used.
Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

5.3.2.4

183

TCRInvalidHashAction Enumeration

Specifies the action to perform on data fetching when hash data is invalid.

Unit
CREncryption

SyntaxTCRInvalidHashAction = (ihFail, ihSkipData, ihIgnoreError);

ValuesValue
ihFailihIgnoreError
ihSkipData© 1997-2019
Devart. All Rights
Reserved.

5.4

CRVio

5.4.1

Enumerations

Meaning
The EInvalidHash exception is raised and further data readingfrom the server is interrupted.
In spite of the fact that the data is not valid, the value is set in thefield. No exception is raised.
The value of the field for this record is set to Null. No exception israised.
Request Support

DAC Forum

Provide Feedback

Enumerations in the CRVio unit.

Enumerations
Name

Description
Specifies the version of theInternet Protocol

TIPVersion© 1997-2019
Devart. All Rights
Reserved.
5.4.1.1

Request Support

TIPVersion Enumeration

Specifies the version of the Internet Protocol

Unit© 2019 Devart

DAC Forum

Provide Feedback

184

SQL Server Data Access Components

CRVio

SyntaxTIPVersion = (ivIPv4, ivIPv6, ivIPBoth);

ValuesValue
ivIPBothivIPv4ivIPv6

MeaningSpecifies that either IPv6 or IPv4 Internet Protocol version is used
Specifies that the IPv4 Internet Protocol version is used
Specifies that the IPv6 Internet Protocol version is used

Remarks
Note: when the TIPVersion property is set to ivIPBoth , there occurs an attempt to connect
via IPv6 (if it is enabled in the OS); if the attempt fails - there occurs an attempt to connect via
IPv4.

See Also
TMSConnectionOptions.IPVersion© 1997-2019
Devart. All Rights
Reserved.

5.5

Request Support

DAC Forum

Provide Feedback

DAAlerter
This unit contains the base class for the TMSAlerter component.

ClassesName

Description
A base class that defines
functionality for database
event notification.

TDAAlerter© 1997-2019
Devart. All Rights
Reserved.
5.5.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the DAAlerter unit.

Classes© 2019 DevartReference

Name

Description
A base class that defines
functionality for database
event notification.

TDAAlerter© 1997-2019
Devart. All Rights
Reserved.
5.5.1.1

185

Request Support

DAC Forum

Provide Feedback

TDAAlerter ClassA base class that defines functionality for database event notification.
For a list of all members of this type, see TDAAlerter members.

Unit
DAAlerter

SyntaxTDAAlerter = class(TComponent);

Remarks
TDAAlerter is a base class that defines functionality for descendant classes support database
event notification. Applications never use TDAAlerter objects directly. Instead they use
descendants of TDAAlerter.
The TDAAlerter component allows you to register interest in and handle events posted by adatabase server. Use TDAAlerter to handle events for responding to actions and databasechanges made by other applications. To get events, an application must register required
events. To do this, set the Events property to the required events and call the Start method.
When one of the registered events occurs OnEvent handler is called.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.5.1.1.1 Members

TDAAlerter class overview.

Properties
Name

Description

ActiveUsed to determine if
TDAAlerter waits for© 2019 Devart

186

SQL Server Data Access Components

messages.
Used to automaticallyregister events wheneverconnection opens.

AutoRegister

Methods
Name

Start

Description
Sends an event with Nameand content Message.
Starts waiting process.

Stop

Stops waiting process.

SendEvent

EventsName

Description
Occurs if an exception
occurs in waiting process

OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.5.1.1.2 Properties

Properties of the TDAAlerter class.
For a complete list of the TDAAlerter class members, see the TDAAlerter Members topic.

PublicName

Description
Used to determine if
TDAAlerter waits formessages.
Used to automaticallyregister events wheneverconnection opens.

ActiveAutoRegister

See Also
TDAAlerter Class
TDAAlerter Class Members© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

187

Devart. All Rights
Reserved.
5.5.1.1.2.1 Active Property

Used to determine if TDAAlerter waits for messages.

Class
TDAAlerter

Syntaxproperty Active: boolean default False;

Remarks
Check the Active property to know whether TDAlerter waits for messages or not. Set it toTrue to register events.

See Also
Start
Stop

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.5.1.1.2.2 AutoRegister Property

Used to automatically register events whenever connection opens.

Class
TDAAlerter

Syntaxproperty AutoRegister: boolean default False;

Remarks
Set the AutoRegister property to True to automatically register events whenever connection
opens.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

188

SQL Server Data Access Components

5.5.1.1.3 Methods

Methods of the TDAAlerter class.
For a complete list of the TDAAlerter class members, see the TDAAlerter Members topic.

PublicName
SendEventDescription
Sends an event with Nameand content Message.

Start

Starts waiting process.

Stop

Stops waiting process.

See Also
TDAAlerter Class
TDAAlerter Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.5.1.1.3.1 SendEvent Method

Sends an event with Name and content Message.

Class
TDAAlerter

Syntax
procedure SendEvent(const EventName: string; const Message:string);Parameters
EventName
Holds the event name.
Message
Holds the content Message of the event.

Remarks
Use SendEvent procedure to send an event with Name and content Message.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

189

Reserved.
5.5.1.1.3.2 Start Method

Starts waiting process.

Class
TDAAlerter

Syntax
procedure Start;

Remarks
Call the Start method to run waiting process. After starting TDAAlerter waits for messages
with names defined by the Events property.

See Also
Stop
Active© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.5.1.1.3.3 Stop Method

Stops waiting process.

Class
TDAAlerter

Syntax
procedure Stop;

Remarks
Call Stop method to end waiting process.

See Also
Start© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

190

SQL Server Data Access Components

Reserved.
5.5.1.1.4 Events

Events of the TDAAlerter class.
For a complete list of the TDAAlerter class members, see the TDAAlerter Members topic.

PublicName

Description
Occurs if an exception
occurs in waiting process

OnErrorSee Also
TDAAlerter Class
TDAAlerter Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.5.1.1.4.1 OnError Event

Occurs if an exception occurs in waiting process

Class
TDAAlerter

Syntaxproperty OnError: TAlerterErrorEvent;Remarks
The OnError event occurs if an exception occurs in waiting process. Alerter stops in thiscase. The exception can be accessed using the E parameter.

© 1997-2019
Devart. All Rights
Reserved.

5.6

Request Support

DAC Forum

Provide Feedback

DADumpThis unit contains the base class for the TMSDump component.

Classes© 2019 DevartReference

Name

191

Description
A base class that defines
functionality for descendantclasses that dump databaseobjects to a script.
This class allows setting up
the behaviour of the
TDADump class.

TDADump

TDADumpOptions

Types
Name

Description
This type is used for the
TDADump.OnBackupProgr
ess event.
This type is used for the
TDADump.OnRestoreProgr
ess event.

TDABackupProgressEvent

TDARestoreProgressEvent© 1997-2019
Devart. All Rights
Reserved.
5.6.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the DADump unit.

ClassesName

Description
A base class that defines
functionality for descendantclasses that dump databaseobjects to a script.
This class allows setting up
the behaviour of the
TDADump class.

TDADump

TDADumpOptions© 1997-2019
Devart. All Rights
Reserved.
5.6.1.1

Request Support

DAC Forum

Provide Feedback

TDADump ClassA base class that defines functionality for descendant classes that dump database objects toa script.
© 2019 Devart

192

SQL Server Data Access Components

For a list of all members of this type, see TDADump members.

Unit
DADumpSyntaxTDADump = class(TComponent);

Remarks
TDADump is a base class that defines functionality for descendant classes that dump
database objects to a script. Applications never use TDADump objects directly. Instead theyuse descendants of TDADump.
Use TDADump descedants to dump database objects, such as tables, stored procedures,and functions for backup or for transferring the data to another SQL server. The dump
contains SQL statements to create the table or other database objects and/or populate thetable.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.1 Members

TDADump class overview.

Properties
Name
Connection

Debug

Options
SQL
TableNames

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the
behaviour of a TDADumpcomponent.
Used to set or get the dump
script.
Used to set the names of thetables to dump.
© 2019 DevartReference

193

Methods
Name

Description
Dumps database objects to
the TDADump.SQL
property.
Dumps the results of aparticular query.
Dumps database objects tothe specified file.
Dumps database objects tothe stream.
Executes a script containedin the SQL property.
Executes a script from a file.

BackupBackupQuery
BackupToFile
BackupToStream
RestoreRestoreFromFile

Executes a script received
from the stream.

RestoreFromStream

EventsName

Description
Occurs to indicate the
TDADump.Backup,
M:Devart.Dac.TDADump.Ba
ckupToFile(System.String)or
M:Devart.Dac.TDADump.Ba
ckupToStream(Borland.Vcl.
TStream) method execution
progress.
Occurs when SQL Server
raises some error on
TDADump.Restore.
Occurs to indicate the
TDADump.Restore,
TDADump.RestoreFromFile, or
TDADump.RestoreFromStr
eam method execution
progress.

OnBackupProgress

OnError

OnRestoreProgress© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

194

SQL Server Data Access Components

Reserved.
5.6.1.1.2 Properties

Properties of the TDADump class.
For a complete list of the TDADump class members, see the TDADump Members topic.

PublicName

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to specify the
behaviour of a TDADumpcomponent.

Connection

Options

Published
Name

Description
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to set or get the dump
script.
Used to set the names of thetables to dump.

Debug

SQL
TableNames

See Also
TDADump Class
TDADump Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.2.1 Connection Property

Used to specify a connection object that will be used to connect to a data store.

Class
TDADump© 2019 DevartReference

195

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomDAConnection or its
descendant class objects.
At runtime, link an instance of a TCustomDAConnection descendant to the Connection
property.

See Also
TCustomDAConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.2.2 Debug Property

Used to display executing statement, all its parameters' values, and the type of parameters.

Class
TDADump

Syntaxproperty Debug: boolean default False;

Remarks
Set the Debug property to True to display executing statement and all its parameters' values.
Also displays the type of parameters.
You should add the SdacVcl unit to the uses clause of any unit in your project to make the
Debug property work.
Note: If TMSSQLMonitor is used in the project and the TMSSQLMonitor.Active property is set
to False, the debug window is not displayed.

See Also
TCustomDADataSet.Debug
TCustomDASQL.Debug© 2019 Devart

196

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.2.3 Options Property

Used to specify the behaviour of a TDADump component.

Class
TDADump

Syntaxproperty Options: TDADumpOptions;Remarks
Use the Options property to specify the behaviour of a TDADump component.
Descriptions of all options are in the table below.

Option Name

Description
Used to add drop statements to a script
before creating statements.
Used to explicitly specify the table fields
names when generating the INSERT SQL
query. The default value is False.
Used to add a comment header to a script.
Used for TDADump to quote all databaseobject names in generated SQL
statements.

AddDropCompleteInsert
GenerateHeader
QuoteNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.2.4 SQL Property

Used to set or get the dump script.

Class
TDADump

Syntaxproperty SQL: TStrings;© 2019 DevartReference

197

Remarks
Use the SQL property to get or set the dump script. The SQL property stores script that is
executed by the Restore method. This property will store the result of Backup and
BackupQuery. At design time the SQL property can be edited by invoking the String List editor
in Object Inspector.

See Also
RestoreBackupBackupQuery© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.2.5 TableNames Property

Used to set the names of the tables to dump.

Class
TDADump

Syntaxproperty TableNames: string;

Remarks
Use the TableNames property to set the names of the tables to dump. Table names must be
separated with commas. If it is empty, the Backup method will dump all available tables.

See Also
Backup© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3 Methods

Methods of the TDADump class.
For a complete list of the TDADump class members, see the TDADump Members topic.

Public© 2019 Devart

198

SQL Server Data Access Components

Name

Description
Dumps database objects to
the TDADump.SQL
property.
Dumps the results of aparticular query.
Dumps database objects tothe specified file.
Dumps database objects tothe stream.
Executes a script containedin the SQL property.
Executes a script from a file.
Executes a script received
from the stream.

BackupBackupQuery
BackupToFile
BackupToStream
RestoreRestoreFromFile
RestoreFromStream

See Also
TDADump Class
TDADump Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.1 Backup Method

Dumps database objects to the SQL property.

Class
TDADump

Syntax
procedure Backup;

Remarks
Call the Backup method to dump database objects. The result script will be stored in the SQL
property.

See Also
SQL
Restore© 2019 DevartReference

199

BackupToFile
BackupToStream
BackupQuery© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.2 BackupQuery Method

Dumps the results of a particular query.

Class
TDADump

Syntax
procedure BackupQuery(const Query: string);
Parameters
Query
Holds a query used for data selection.

Remarks
Call the BackupQuery method to dump the results of a particular query. Query must be avalid select statement. If this query selects data from several tables, only data of the first tablein the from list will be dumped.

See Also
RestoreBackupBackupToFile
BackupToStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.6.1.1.3.3 BackupToFile Method

Dumps database objects to the specified file.

Class
TDADump© 2019 Devart

DAC Forum

Provide Feedback

200

SQL Server Data Access Components

Syntax
procedure BackupToFile(const FileName: string; const Query:
string = '');
Parameters
FileName
Holds the file name to dump database objects to.
QueryYour query to receive the data for dumping.

Remarks
Call the BackupToFile method to dump database objects to the specified file.

See Also
RestoreFromStream
BackupBackupToStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.4 BackupToStream Method

Dumps database objects to the stream.

Class
TDADump

Syntax
procedure BackupToStream(Stream: TStream; const Query: string ='');Parameters
StreamHolds the stream to dump database objects to.
QueryYour query to receive the data for dumping.

Remarks
Call the BackupToStream method to dump database objects to the stream.
© 2019 DevartReference201

See Also
RestoreFromStream
BackupBackupToFile© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.5 Restore Method

Executes a script contained in the SQL property.

Class
TDADump

Syntax
procedure Restore;

Remarks
Call the Restore method to execute a script contained in the SQL property.

See Also
RestoreFromFile
RestoreFromStream
Backup
SQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.6 RestoreFromFile Method

Executes a script from a file.

Class
TDADump

Syntax
procedure RestoreFromFile(const FileName: string);© 2019 Devart

202

SQL Server Data Access Components

Parameters
FileName
Holds the file name to execute a script from.

Remarks
Call the RestoreFromFile method to execute a script from the specified file.

See Also
RestoreRestoreFromStream
BackupToFile© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.3.7 RestoreFromStream Method

Executes a script received from the stream.

Class
TDADump

Syntax
procedure RestoreFromStream(Stream: TStream);
Parameters
StreamHolds a stream to receive a script to be executed.

Remarks
Call the RestoreFromStream method to execute a script received from the stream.

See Also
RestoreRestoreFromFile
BackupToStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

203

5.6.1.1.4 Events

Events of the TDADump class.
For a complete list of the TDADump class members, see the TDADump Members topic.

Published
Name

Description
Occurs to indicate the
TDADump.Backup,
M:Devart.Dac.TDADump.Ba
ckupToFile(System.String)or
M:Devart.Dac.TDADump.Ba
ckupToStream(Borland.Vcl.
TStream) method execution
progress.
Occurs when SQL Server
raises some error on
TDADump.Restore.
Occurs to indicate the
TDADump.Restore,
TDADump.RestoreFromFile, or
TDADump.RestoreFromStr
eam method execution
progress.

OnBackupProgress

OnError

OnRestoreProgress

See Also
TDADump Class
TDADump Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.4.1 OnBackupProgress Event

Occurs to indicate the Backup, M:Devart.Dac.TDADump.BackupToFile(System.String) or
M:Devart.Dac.TDADump.BackupToStream(Borland.Vcl.TStream) method execution
progress.

Class
TDADump© 2019 Devart

204

SQL Server Data Access Components

Syntaxproperty OnBackupProgress: TDABackupProgressEvent;Remarks
The OnBackupProgress event occurs several times during the dumping process of the
Backup, M:Devart.Dac.TDADump.BackupToFile(System.String), or
M:Devart.Dac.TDADump.BackupToStream(Borland.Vcl.TStream) method execution andindicates its progress. ObjectName parameter indicates the name of the currently dumping
database object. ObjectNum shows the number of the current database object in the backup
queue starting from zero. ObjectCount shows the quantity of database objects to dump.
Percent parameter shows the current percentage of the current table data dumped, not thecurrent percentage of the entire dump process.

See Also
BackupBackupToFile
BackupToStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.1.4.2 OnError Event

Occurs when SQL Server raises some error on Restore.

Class
TDADump

Syntaxproperty OnError: TOnErrorEvent;Remarks
The OnError event occurs when SQL Server raises some error on Restore.
Action indicates the action to take when the OnError handler exits. On entry into the handler,
Action is always set to eaException.
Note: You should add the DAScript module to the 'uses' list to use the OnError event handler.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

205

Reserved.
5.6.1.1.4.3 OnRestoreProgress Event

Occurs to indicate the Restore, RestoreFromFile, or RestoreFromStream method execution
progress.

Class
TDADump

Syntaxproperty OnRestoreProgress: TDARestoreProgressEvent;Remarks
The OnRestoreProgress event occurs several times during the dumping process of the
Restore, RestoreFromFile, or RestoreFromStream method execution and indicates its
progress. The Percent parameter of the OnRestoreProgress event handler indicates thepercentage of the whole restore script execution.

See Also
RestoreRestoreFromFile
RestoreFromStream© 1997-2019
Devart. All Rights
Reserved.
5.6.1.2

Request Support

DAC Forum

Provide Feedback

TDADumpOptions ClassThis class allows setting up the behaviour of the TDADump class.
For a list of all members of this type, see TDADumpOptions members.

Unit
DADumpSyntaxTDADumpOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

206

SQL Server Data Access Components

5.6.1.2.1 Members

TDADumpOptions class overview.

Properties
Name

Description
Used to add drop
statements to a script before
creating statements.
Used to explicitly specify thetable fields names whengenerating the INSERT SQL
query. The default value isFalse.
Used to add a comment
header to a script.
Used for TDADump to quote
all database object names ingenerated SQL statements.

AddDropCompleteInsert

GenerateHeader
QuoteNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.2.2 Properties

Properties of the TDADumpOptions class.
For a complete list of the TDADumpOptions class members, see the TDADumpOptions
Members topic.

Published
Name
AddDropCompleteInsert

GenerateHeader
QuoteNames

Description
Used to add drop
statements to a script before
creating statements.
Used to explicitly specify thetable fields names whengenerating the INSERT SQL
query. The default value isFalse.
Used to add a comment
header to a script.
Used for TDADump to quote
all database object names in© 2019 DevartReference207

generated SQL statements.

See Also
TDADumpOptions Class
TDADumpOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.2.2.1 AddDrop Property

Used to add drop statements to a script before creating statements.

Class
TDADumpOptions

Syntaxproperty AddDrop: boolean default True;

Remarks
Use the AddDrop property to add drop statements to a script before creating statements.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.2.2.2 CompleteInsert Property

Used to explicitly specify the table fields names when generating the INSERT SQL query. The
default value is False.

Class
TDADumpOptions

Syntaxproperty CompleteInsert: boolean default False;

Remarks
If the CompleteInsert property is set to True, SQL query will include the field names, forexample:© 2019 Devart

208

SQL Server Data Access Components

INSERT INTO dept(deptno, dname, loc) VALUES ('10', 'ACCOUNTING', 'NEW YORK')
If False, it won't include the field names, for example:
INSERT INTO dept VALUES ('10', 'ACCOUNTING', 'NEW YORK');© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.2.2.3 GenerateHeader Property

Used to add a comment header to a script.

Class
TDADumpOptions

Syntaxproperty GenerateHeader: boolean default True;

Remarks
Use the GenerateHeader property to add a comment header to a script. It contains script
generation date, DAC version, and some other information.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.6.1.2.2.4 QuoteNames Property

Used for TDADump to quote all database object names in generated SQL statements.

Class
TDADumpOptions

Syntaxproperty QuoteNames: boolean default False;

Remarks
If the QuoteNames property is True, TDADump quotes all database object names ingenerated SQL statements.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

5.6.2

209

Types
Types in the DADump unit.

Types
Name

Description
This type is used for the
TDADump.OnBackupProgr
ess event.
This type is used for the
TDADump.OnRestoreProgr
ess event.

TDABackupProgressEvent

TDARestoreProgressEvent© 1997-2019
Devart. All Rights
Reserved.
5.6.2.1

Request Support

DAC Forum

Provide Feedback

TDABackupProgressEvent Procedure ReferenceThis type is used for the TDADump.OnBackupProgress event.

Unit
DADumpSyntaxTDABackupProgressEvent = procedure (Sender: TObject; ObjectName:string; ObjectNum: integer; ObjectCount: integer; Percent:integer) of object;Parameters
SenderAn object that raised the event.
ObjectName
The name of the currently dumping database object.
ObjectNum
The number of the current database object in the backup queue starting from zero.
ObjectCountThe quantity of database objects to dump.
Percent
The current percentage of the current table data dumped.

© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

210

5.6.2.2

SQL Server Data Access Components

TDARestoreProgressEvent Procedure ReferenceThis type is used for the TDADump.OnRestoreProgress event.

Unit
DADumpSyntaxTDARestoreProgressEvent = procedure (Sender: TObject; Percent:integer) of object;Parameters
SenderAn object that raised the event.
Percent
The percentage of the whole restore script execution.

© 1997-2019
Devart. All Rights
Reserved.

5.7

Request Support

DAC Forum

Provide Feedback

DALoaderThis unit contains the base class for the TMSLoader component.

ClassesName
TDAColumn
TDAColumns
TDALoader
TDALoaderOptions

Description
Represents the attributes forcolumn loading.
Holds a collection of
TDAColumn objects.
This class allows loading
external data into database.
Allows loading external data
into database.

Types
Name
TDAPutDataEvent

Description
This type is used for the
TDALoader.OnPutData
event.

© 2019 DevartReferenceThis type is used for the
TDALoader.OnGetColumnD
ata event.
This type is used for the
TDALoader.OnProgress
event.

TGetColumnDataEvent

TLoaderProgressEvent© 1997-2019
Devart. All Rights
Reserved.
5.7.1

Request Support

211

DAC Forum

Provide Feedback

ClassesClasses in the DALoader unit.

ClassesName

Description
Represents the attributes forcolumn loading.
Holds a collection of
TDAColumn objects.
This class allows loading
external data into database.
Allows loading external data
into database.

TDAColumn
TDAColumns
TDALoader
TDALoaderOptions© 1997-2019
Devart. All Rights
Reserved.
5.7.1.1

Request Support

DAC Forum

Provide Feedback

TDAColumn Class

Represents the attributes for column loading.
For a list of all members of this type, see TDAColumn members.

Unit
DALoaderSyntaxTDAColumn = class(TCollectionItem);Remarks
Each TDALoader uses TDAColumns to maintain a collection of TDAColumn objects.
© 2019 Devart

212

SQL Server Data Access Components

TDAColumn object represents the attributes for column loading. Every TDAColumn object
corresponds to one of the table fields with the same name as its TDAColumn.Name property.
To create columns at design-time use the column editor of the TDALoader component.

See Also
TDALoader
TDAColumns© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.1.1 Members

TDAColumn class overview.

Properties
Name

Description
Used to specify the types ofvalues that will be loaded.
Used to specify the fieldname of loading table.

FieldTypeName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.1.2 Properties

Properties of the TDAColumn class.
For a complete list of the TDAColumn class members, see the TDAColumn Members topic.

Published
Name
FieldType
Name

Description
Used to specify the types ofvalues that will be loaded.
Used to specify the fieldname of loading table.

See Also
TDAColumn Class
TDAColumn Class Members© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

213

Provide Feedback

5.7.1.1.2.1 FieldType Property

Used to specify the types of values that will be loaded.

Class
TDAColumn

Syntaxproperty FieldType: TFieldType default ftString;

Remarks
Use the FieldType property to specify the types of values that will be loaded. Field types forcolumns may not match data types for the corresponding fields in the database table.
TDALoader will cast data values to the types of their fields.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.1.2.2 Name Property

Used to specify the field name of loading table.

Class
TDAColumn

Syntaxproperty Name: string;

Remarks
Each TDAColumn corresponds to one field of the loading table. Use the Name property to
specify the name of this field.

See Also
FieldType© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

214

5.7.1.2

SQL Server Data Access Components

TDAColumns Class

Holds a collection of TDAColumn objects.
For a list of all members of this type, see TDAColumns members.

Unit
DALoaderSyntaxTDAColumns = class(TOwnedCollection);

Remarks
Each TDAColumns holds a collection of TDAColumn objects. TDAColumns maintains an
index of the columns in its Items array. The Count property contains the number of columns
in the collection. At design-time, use the Columns editor to add, remove, or modify columns.

See Also
TDALoader
TDAColumn© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.2.1 Members

TDAColumns class overview.

Properties
Name

Description
Used to access individualcolumns.

Items© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.2.2 Properties

Properties of the TDAColumns class.
For a complete list of the TDAColumns class members, see the TDAColumns Members
topic.

© 2019 DevartReference

215

PublicName

Description
Used to access individualcolumns.

Items

See Also
TDAColumns Class
TDAColumns Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.2.2.1 Items Property(Indexer)

Used to access individual columns.

Class
TDAColumns

Syntaxproperty Items[Index: integer]: TDAColumn; default;
Parameters
Index
Holds the Index of TDAColumn to refer to.

Remarks
Use the Items property to access individual columns. The value of the Index parametercorresponds to the Index property of TDAColumn.

See Also
TDAColumn© 1997-2019
Devart. All Rights
Reserved.
5.7.1.3

Request Support

DAC Forum

TDALoader ClassThis class allows loading external data into database.
For a list of all members of this type, see TDALoader members.

© 2019 Devart

Provide Feedback

216

SQL Server Data Access Components

Unit
DALoaderSyntax
TDALoader = class(TComponent);

Remarks
TDALoader allows loading external data into database. To specify the name of loading table
set the TDALoader.TableName property. Use the TDALoader.Columns property to accessindividual columns. Write the TDALoader.OnGetColumnData or TDALoader.OnPutData event
handlers to read external data and pass it to the database. Call the TDALoader.Load method
to start loading data.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.1 Members

TDALoader class overview.

Properties
Name
Columns

Connection

TableName

Description
Used to add a TDAColumn
object for each field that will
be loaded.
Used to specify
TCustomDAConnection inwhich TDALoader will be
executed.
Used to specify the name of
the table to which data will
be loaded.

Methods
Name
CreateColumns

Description
Creates TDAColumn
objects for all fields of thetable with the same nameas TDALoader.TableName.
© 2019 DevartReference

Load

217

Starts loading data.
Loads data from thespecified dataset.
Overloaded. Puts the valueof individual columns.

LoadFromDataSet
PutColumnData

EventsName

Description
Occurs when it is needed toput column values.
Occurs if handling dataloading progress of the
TDALoader.LoadFromData
Set method is needed.
Occurs when putting loading
data by rows is needed.

OnGetColumnData

OnProgress

OnPutData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.2 Properties

Properties of the TDALoader class.
For a complete list of the TDALoader class members, see the TDALoader Members topic.

PublicName
Columns

Connection

TableName

See Also
TDALoader Class© 2019 Devart

Description
Used to add a TDAColumn
object for each field that will
be loaded.
Used to specify
TCustomDAConnection inwhich TDALoader will be
executed.
Used to specify the name of
the table to which data will
be loaded.

218

SQL Server Data Access Components

TDALoader Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.2.1 Columns Property

Used to add a TDAColumn object for each field that will be loaded.

Class
TDALoader

Syntaxproperty Columns: TDAColumns stored IsColumnsStored;

Remarks
Use the Columns property to add a TDAColumn object for each field that will be loaded.

See Also
TDAColumns© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.2.2 Connection Property

Used to specify TCustomDAConnection in which TDALoader will be executed.

Class
TDALoader

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify TCustomDAConnection in which TDALoader will be
executed. If Connection is not connected, the Load method calls
TCustomDAConnection.Connect.

See Also© 2019 DevartReference

219

TCustomDAConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.2.3 TableName Property

Used to specify the name of the table to which data will be loaded.

Class
TDALoader

Syntaxproperty TableName: string;

Remarks
Set the TableName property to specify the name of the table to which data will be loaded. Add
TDAColumn objects to Columns for the fields that are needed to be loaded.

See Also
TDAColumn
TCustomDAConnection.GetTableNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.3 Methods

Methods of the TDALoader class.
For a complete list of the TDALoader class members, see the TDALoader Members topic.

PublicNameCreateColumns
Load
LoadFromDataSet© 2019 Devart

Description
Creates TDAColumn
objects for all fields of thetable with the same nameas TDALoader.TableName.
Starts loading data.
Loads data from thespecified dataset.

220

SQL Server Data Access Components

Overloaded. Puts the valueof individual columns.

PutColumnData

See Also
TDALoader Class
TDALoader Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.3.1 CreateColumns Method

Creates TDAColumn objects for all fields of the table with the same name as TableName.

Class
TDALoader

Syntax
procedure CreateColumns;

Remarks
Call the CreateColumns method to create TDAColumn objects for all fields of the table withthe same name as TableName. If columns were created before, they will be recreated. You
can call CreateColumns from the component popup menu at design-time. After you cancustomize column loading by setting properties of TDAColumn objects.

See Also
TDAColumn
TableName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.3.2 Load Method

Starts loading data.

Class
TDALoader© 2019 DevartReference

221

Syntax
procedure Load; virtual;

Remarks
Call the Load method to start loading data. At first it is necessary to create columns and write
one of the OnPutData or OnGetColumnData event handlers.

See Also
OnGetColumnData
OnPutData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.3.3 LoadFromDataSet Method

Loads data from the specified dataset.

Class
TDALoader

Syntax
procedure LoadFromDataSet(DataSet: TDataSet);
Parameters
DataSetHolds the dataset to load data from.

Remarks
Call the LoadFromDataSet method to load data from the specified dataset. There is no needto create columns and write event handlers for OnPutData and OnGetColumnData before
calling this method.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

222

SQL Server Data Access Components

5.7.1.3.3.4 PutColumnData Method

Puts the value of individual columns.

Class
TDALoaderOverload List
Name
Description
PutColumnData(Col: integer; Row: integer; Puts the value of individual columns by theconst Value: variant)column index.
PutColumnData(const ColName: string; Puts the value of individual columns by the
Row: integer; const Value: variant)column name.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
Puts the value of individual columns by the column index.

Class
TDALoader

Syntax
procedure PutColumnData(Col: integer; Row: integer; const Value:
variant); overload; virtual;Parameters
Col
Holds the index of a loading column. The first column has index 0.
Row
Holds the number of loading row. Row starts from 1.
Value
Holds the column value.

Remarks
Call the PutColumnData method to put the value of individual columns. The Col parameter
indicates the index of loading column. The first column has index 0. The Row parameter
indicates the number of the loading row. Row starts from 1.
This overloaded method works faster because it searches the right index by its index, not by
the index name.
© 2019 DevartReference223

The value of a column should be assigned to the Value parameter.

See Also
TDALoader.OnPutData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Puts the value of individual columns by the column name.

Class
TDALoader

Syntax
procedure PutColumnData(const ColName: string; Row: integer;
const Value: variant); overload;
Parameters
ColNameHods the name of a loading column.
Row
Holds the number of loading row. Row starts from 1.
Value
Holds the column value.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.4 Events

Events of the TDALoader class.
For a complete list of the TDALoader class members, see the TDALoader Members topic.

PublicName
OnGetColumnData

OnProgress© 2019 Devart

Description
Occurs when it is needed toput column values.
Occurs if handling dataloading progress of the
TDALoader.LoadFromData
Set method is needed.

224

SQL Server Data Access Components

Occurs when putting loading
data by rows is needed.

OnPutData

See Also
TDALoader Class
TDALoader Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.4.1 OnGetColumnData Event

Occurs when it is needed to put column values.

Class
TDALoader

Syntaxproperty OnGetColumnData: TGetColumnDataEvent;Remarks
Write the OnGetColumnData event handler to put column values. TDALoader calls the
OnGetColumnData event handler for each column in the loop. Column points to a
TDAColumn object that corresponds to the current loading column. Use its Name or Index
property to identify what column is loading. The Row parameter indicates the current loading
record. TDALoader increments the Row parameter when all the columns of the current
record are loaded. The first row is 1. Set EOF to True to stop data loading. Fill the Valueparameter by column values. To start loading call the Load method.
Another way to load data is using the OnPutData event.

ExampleThis handler loads 1000 rows.
procedure TfmMain.GetColumnData(Sender: TObject;
Column: TDAColumn; Row: Integer; var Value: Variant;var EOF: Boolean);begin
if Row <= 1000 then begin
case Column.Index of
0: Value := Row;
1: Value := Random(100);
2: Value := Random*100;© 2019 DevartReference

225

3: Value := 'abc01234567890123456789';
4: Value := Date;
else
Value := Null;
end;
end
else
EOF := True;
end;

See Also
OnPutData
Load© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.3.4.2 OnProgress Event

Occurs if handling data loading progress of the LoadFromDataSet method is needed.

Class
TDALoader

Syntaxproperty OnProgress: TLoaderProgressEvent;Remarks
Add a handler to this event if you want to handle data loading progress of the
LoadFromDataSet method.

See Also
LoadFromDataSet© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.7.1.3.4.3 OnPutData Event

Occurs when putting loading data by rows is needed.

Class
TDALoader© 2019 Devart

Provide Feedback

226

SQL Server Data Access Components

Syntaxproperty OnPutData: TDAPutDataEvent;Remarks
Write the OnPutData event handler to put loading data by rows.
Note that rows should be loaded from the first in the ascending order.
To start loading, call the Load method.

ExampleThis handler loads 1000 rows.
procedure TfmMain.PutData(Sender: TDALoader);varCount: Integer;i: Integer;
begin
Count := StrToInt(edRows.Text);
for i := 1 to Count dobegin
Sender.PutColumnData(0, i, 1);
Sender.PutColumnData(1, i, Random(100));
Sender.PutColumnData(2, i, Random*100);
Sender.PutColumnData(3, i, 'abc01234567890123456789');
Sender.PutColumnData(4, i, Date);
end;
end;

See Also
TDALoader.PutColumnData
Load
OnGetColumnData© 1997-2019
Devart. All Rights
Reserved.
5.7.1.4

Request Support

DAC Forum

Provide Feedback

TDALoaderOptions Class

Allows loading external data into database.
For a list of all members of this type, see TDALoaderOptions members.

Unit
DALoaderSyntax© 2019 DevartReference

227

TDALoaderOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.4.1 Members

TDALoaderOptions class overview.

Properties
Name

Description
Forces SDAC to fill thebuffer with null values after
loading a row to the
database.

UseBlankValues© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.7.1.4.2 Properties

Properties of the TDALoaderOptions class.
For a complete list of the TDALoaderOptions class members, see the TDALoaderOptions
Members topic.

PublicName

Description
Forces SDAC to fill thebuffer with null values after
loading a row to the
database.

UseBlankValues

See Also
TDALoaderOptions Class
TDALoaderOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

228

SQL Server Data Access Components

5.7.1.4.2.1 UseBlankValues Property

Forces SDAC to fill the buffer with null values after loading a row to the database.

Class
TDALoaderOptions

Syntaxproperty UseBlankValues: boolean default True;

Remarks
Used to force SDAC to fill the buffer with null values after loading a row to the database.

© 1997-2019
Devart. All Rights
Reserved.
5.7.2

Request Support

DAC Forum

Provide Feedback

Types
Types in the DALoader unit.

Types
Name

Description
This type is used for the
TDALoader.OnPutData
event.
This type is used for the
TDALoader.OnGetColumnD
ata event.
This type is used for the
TDALoader.OnProgress
event.

TDAPutDataEvent

TGetColumnDataEvent

TLoaderProgressEvent© 1997-2019
Devart. All Rights
Reserved.
5.7.2.1

Request Support

DAC Forum

Provide Feedback

TDAPutDataEvent Procedure ReferenceThis type is used for the TDALoader.OnPutData event.

Unit
DALoader© 2019 DevartReference

229

SyntaxTDAPutDataEvent = procedure (Sender: TDALoader) of object;Parameters
SenderAn object that raised the event.

© 1997-2019
Devart. All Rights
Reserved.
5.7.2.2

Request Support

DAC Forum

Provide Feedback

TGetColumnDataEvent Procedure ReferenceThis type is used for the TDALoader.OnGetColumnData event.

Unit
DALoaderSyntaxTGetColumnDataEvent = procedure (Sender: TObject; Column:
TDAColumn; Row: integer; var Value: variant; var IsEOF: boolean)of object;Parameters
SenderAn object that raised the event.
ColumnPoints to TDAColumn object that corresponds to the current loading column.
Row
Indicates the current loading record.
Value
Holds column values.
IsEOF
True, if data loading needs to be stopped.

© 1997-2019
Devart. All Rights
Reserved.
5.7.2.3

Request Support

DAC Forum

TLoaderProgressEvent Procedure ReferenceThis type is used for the TDALoader.OnProgress event.

Unit© 2019 Devart

Provide Feedback

230

SQL Server Data Access Components

DALoaderSyntaxTLoaderProgressEvent = procedure (Sender: TObject; Percent:integer) of object;Parameters
SenderAn object that raised the event.
Percent
Percentage of the load operation progress.

© 1997-2019
Devart. All Rights
Reserved.

5.8

Request Support

DAC Forum

Provide Feedback

DAScript
This unit contains the base class for the TMSScript component.

ClassesName
TDAScript

TDAStatement

TDAStatements

Description
Makes it possible to execute
several SQL statements one
by one.
This class has attributes andmethods for controlling
single SQL statement of ascript.
Holds a collection of
TDAStatement objects.

Types
Name
TAfterStatementExecuteEvent

TBeforeStatementExecuteEvent
TOnErrorEvent

Description
This type is used for the
TDAScript.AfterExecute
event.
This type is used for the
TDAScript.BeforeExecute
event.
This type is used for the
TDAScript.OnError event.
© 2019 DevartReference

231

Enumerations
Name

Description
Indicates the action to takewhen the OnError handler
exits.

TErrorAction© 1997-2019
Devart. All Rights
Reserved.
5.8.1

Request Support

DAC Forum

Provide Feedback

ClassesClasses in the DAScript unit.

ClassesName

Description
Makes it possible to execute
several SQL statements one
by one.
This class has attributes andmethods for controlling
single SQL statement of ascript.
Holds a collection of
TDAStatement objects.

TDAScript

TDAStatement

TDAStatements© 1997-2019
Devart. All Rights
Reserved.
5.8.1.1

Request Support

DAC Forum

TDAScript Class

Makes it possible to execute several SQL statements one by one.
For a list of all members of this type, see TDAScript members.

Unit
DAScript

Syntax
TDAScript = class(TComponent);

Remarks© 2019 Devart

Provide Feedback

232

SQL Server Data Access Components

Often it is necessary to execute several SQL statements one by one. This can be performed
using a lot of components such as TCustomDASQL descendants. Usually it isn't the bestsolution. With only one TDAScript descedant component you can execute several SQL
statements as one. This sequence of statements is called script. To separate single
statements use semicolon (;) or slash (/) and for statements that can contain semicolon, only
slash. Note that slash must be the first character in line.
Errors that occur during execution can be processed in the TDAScript.OnError event handler.
By default, on error TDAScript shows exception and continues execution.

See Also
TCustomDASQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.1 Members

TDAScript class overview.

Properties
Name
Connection

DataSetDebug

Delimiter

EndLineEndOffset
EndPosMacrosDescription
Used to specify theconnection in which thescript will be executed.
Refers to a dataset that
holds the result set of query
execution.
Used to display the script
execution and all its
parameter values.
Used to set the delimiter
string that separates script
statements.
Used to get the current
statement last line number ina script.
Used to get the offset in thelast line of the current
statement.
Used to get the end positionof the current statement.
Used to change SQL script© 2019 DevartReference

SQL
StartLineStartOffset

StartPos

Statements

233

text in design- or run-timeeasily.
Used to get or set script text.
Used to get the current
statement start line number
in a script.
Used to get the offset in thefirst line of the current
statement.
Used to get the start positionof the current statement in ascript.
Contains a list of statements
obtained from the SQL
property.

Methods
Name
BreakExec
ErrorOffset
ExecuteExecuteFile
ExecuteNext
ExecuteStream
MacroByName

Description
Stops script execution.
Used to get the offset of thestatement if the Execute
method raised an exception.
Executes a script.
Executes SQL statements
contained in a file.
Executes the next statementin the script and then stops.
Executes SQL statements
contained in a stream
object.
Finds a Macro with thename passed in Name.

EventsName
AfterExecute

Description
Occurs after a SQL script
execution.

BeforeExecute

Occurs when taking a
specific action before© 2019 Devart

234

SQL Server Data Access Components

executing the current SQL
statement is needed.
Occurs when SQL Server
raises an error.

OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2 Properties

Properties of the TDAScript class.
For a complete list of the TDAScript class members, see the TDAScript Members topic.

PublicName
Connection

DataSetEndLineEndOffset
EndPosStartLineStartOffset

StartPos

Statements

Description
Used to specify theconnection in which thescript will be executed.
Refers to a dataset that
holds the result set of query
execution.
Used to get the current
statement last line number ina script.
Used to get the offset in thelast line of the current
statement.
Used to get the end positionof the current statement.
Used to get the current
statement start line number
in a script.
Used to get the offset in thefirst line of the current
statement.
Used to get the start positionof the current statement in ascript.
Contains a list of statements
obtained from the SQL
property.

© 2019 DevartReference

235

Published
Name

Description
Used to display the script
execution and all its
parameter values.
Used to set the delimiter
string that separates script
statements.
Used to change SQL script
text in design- or run-timeeasily.
Used to get or set script text.

Debug

Delimiter

MacrosSQL

See Also
TDAScript Class
TDAScript Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.1 Connection Property

Used to specify the connection in which the script will be executed.

Class
TDAScript

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify the connection in which the script will be executed. If
Connection is not connected, the Execute method calls the Connect method of Connection.
Set at design-time by selecting from the list of provided TCustomDAConnection objects.
At run-time, set the Connection property to reference an existing TCustomDAConnection
object.

See Also© 2019 Devart

236

SQL Server Data Access Components

TCustomDAConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.2 DataSet Property

Refers to a dataset that holds the result set of query execution.

Class
TDAScript

Syntaxproperty DataSet: TCustomDADataSet;

Remarks
Set the DataSet property to retrieve the results of the SELECT statements execution inside a
script.

See Also
ExecuteNext
Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.3 Debug Property

Used to display the script execution and all its parameter values.

Class
TDAScript

Syntaxproperty Debug: boolean default False;

Remarks
Set the Debug property to True to display executing statement and all its parameters' values.
Also displays the type of parameters.
You should add the SdacVcl unit to the uses clause of any unit in your project to make the© 2019 DevartReference

237

Debug property work.
Note: If TMSSQLMonitor is used in the project and the TMSSQLMonitor.Active property is set
to False, the debug window is not displayed.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.4 Delimiter Property

Used to set the delimiter string that separates script statements.

Class
TDAScript

Syntaxproperty Delimiter: string stored IsDelimiterStored;

Remarks
Use the Delimiter property to set the delimiter string that separates script statements. By
default it is semicolon (;). You can use slash (/) to separate statements that can containsemicolon if the Delimiter property's default value is semicolon. Note that slash must be thefirst character in line.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.5 EndLine Property

Used to get the current statement last line number in a script.

Class
TDAScript

Syntaxproperty EndLine: Int64;

Remarks
Use the EndLine property to get the current statement last line number in a script.

© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

238

SQL Server Data Access Components

5.8.1.1.2.6 EndOffset Property

Used to get the offset in the last line of the current statement.

Class
TDAScript

Syntaxproperty EndOffset: Int64;

Remarks
Use the EndOffset property to get the offset in the last line of the current statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.7 EndPos Property

Used to get the end position of the current statement.

Class
TDAScript

Syntaxproperty EndPos: Int64;

Remarks
Use the EndPos property to get the end position of the current statement (the position of thelast character in the statement) in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.8 Macros Property

Used to change SQL script text in design- or run-time easily.

Class
TDAScript

Syntax© 2019 DevartReference239

property Macros: TMacros stored False;

Remarks
With the help of macros you can easily change SQL script text in design- or run-time. Macrosextend abilities of parameters and allow changing conditions in the WHERE clause or sortorder in the ORDER BY clause. You just insert &MacroName in a SQL query text and change
value of macro by the Macro property editor in design-time or the MacroByName function in
run-time. In time of opening query macro is replaced by its value.

See Also
TMacroMacroByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.8.1.1.2.9 SQL Property

Used to get or set script text.

Class
TDAScript

Syntaxproperty SQL: TStrings;

Remarks
Use the SQL property to get or set script text.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.8.1.1.2.10 StartLine Property

Used to get the current statement start line number in a script.

Class
TDAScript

Syntax© 2019 Devart

240

SQL Server Data Access Components

property StartLine: Int64;

Remarks
Use the StartLine property to get the current statement start line number in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.11 StartOffset Property

Used to get the offset in the first line of the current statement.

Class
TDAScript

Syntaxproperty StartOffset: Int64;

Remarks
Use the StartOffset property to get the offset in the first line of the current statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.2.12 StartPos Property

Used to get the start position of the current statement in a script.

Class
TDAScript

Syntaxproperty StartPos: Int64;

Remarks
Use the StartPos property to get the start position of the current statement (the position of thefirst statement character) in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

241

5.8.1.1.2.13 Statements Property

Contains a list of statements obtained from the SQL property.

Class
TDAScript

Syntaxproperty Statements: TDAStatements;

Remarks
Contains a list of statements that are obtained from the SQL property. Use the AccessStatements property to view SQL statement, set parameters or execute the specifiedstatement. Statements is a zero-based array of statement records. Index specifies the arrayelement to access.
For example, consider the following script:
CREATE TABLE A (FIELD1 INTEGER);INSERT INTO A VALUES(1);INSERT INTO A VALUES(2);INSERT INTO A VALUES(3);CREATE TABLE B (FIELD1 INTEGER);INSERT INTO B VALUES(1);INSERT INTO B VALUES(2);INSERT INTO B VALUES(3);Note: The list of statements is created and filled when the value of Statements property isrequested. That's why the first access to the Statements property can take a long time.

ExampleYou can use the Statements property in the following way:procedure TForm1.Button1Click(Sender: TObject);var
i: integer;
begin
with Script do
begin
for i := 0 to Statements.Count - 1 do
if Copy(Statements[i].SQL, 1, 6) <> 'CREATE' thenStatements[i].Execute;
end;
end;

See Also
TDAStatements© 2019 Devart

242

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3 Methods

Methods of the TDAScript class.
For a complete list of the TDAScript class members, see the TDAScript Members topic.

PublicName
BreakExec

Description
Stops script execution.
Used to get the offset of thestatement if the Execute
method raised an exception.
Executes a script.

ErrorOffset
ExecuteExecutes SQL statements
contained in a file.
Executes the next statementin the script and then stops.
Executes SQL statements
contained in a stream
object.
Finds a Macro with thename passed in Name.

ExecuteFile
ExecuteNext
ExecuteStream
MacroByName

See Also
TDAScript Class
TDAScript Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3.1 BreakExec Method

Stops script execution.

Class
TDAScript

Syntax© 2019 DevartReference

243

procedure BreakExec; virtual;

Remarks
Call the BreakExec method to stop script execution.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3.2 ErrorOffset Method

Used to get the offset of the statement if the Execute method raised an exception.

Class
TDAScript

Syntaxfunction ErrorOffset: Int64;
Return Value
offset of an error.

Remarks
Call the ErrorOffset method to get the offset of the statement if the Execute method raised an
exception.

See Also
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.8.1.1.3.3 Execute Method

Executes a script.

Class
TDAScript

Syntax
procedure Execute; virtual;© 2019 Devart

DAC Forum

Provide Feedback

244

SQL Server Data Access Components

Remarks
Call the Execute method to execute a script. If SQL Server raises an error, the OnError event
occurs.

See Also
ExecuteNext
OnErrorErrorOffset© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3.4 ExecuteFile Method

Executes SQL statements contained in a file.

Class
TDAScript

Syntax
procedure ExecuteFile(const FileName: string);
Parameters
FileName
Holds the file name.

Remarks
Call the ExecuteFile method to execute SQL statements contained in a file. Script doesn't
load full content into memory. Reading and execution is performed by blocks of 64k size.
Therefore, it is optimal to use it for big files.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3.5 ExecuteNext Method

Executes the next statement in the script and then stops.

Class
TDAScript© 2019 DevartReference

245

Syntaxfunction ExecuteNext: boolean; virtual;
Return Value
True, if there are any statements left in the script, False otherwise.

Remarks
Use the ExecuteNext method to execute the next statement in the script statement and stop.
If SQL Server raises an error, the OnError event occurs.

See Also
ExecuteOnErrorErrorOffset© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.3.6 ExecuteStream Method

Executes SQL statements contained in a stream object.

Class
TDAScript

Syntax
procedure ExecuteStream(Stream: TStream);
Parameters
StreamHolds the stream object from which the statements will be executed.

Remarks
Call the ExecuteStream method to execute SQL statements contained in a stream object.
Reading from the stream and execution is performed by blocks of 64k size.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

246

SQL Server Data Access Components

5.8.1.1.3.7 MacroByName Method

Finds a Macro with the name passed in Name.

Class
TDAScript

Syntaxfunction MacroByName(Name: string): TMacro;Parameters
Name
Holds the name of the Macro to search for.
Return Value
the Macro, if a match was found.

Remarks
Call the MacroByName method to find a Macro with the name passed in Name. If a match
was found, MacroByName returns the Macro. Otherwise, an exception is raised. Use thismethod rather than a direct reference to the Items property to avoid depending on the order ofthe entries.
To locate a parameter by name without raising an exception if the parameter is not found, use
the FindMacro method.
To assign the value of macro use the TMacro.Value property.

See Also
TMacroMacros
M:Devart.Dac.TDAScript.FindMacro(System.String)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.4 Events

Events of the TDAScript class.
For a complete list of the TDAScript class members, see the TDAScript Members topic.

Published
Name

Description© 2019 DevartReference247

Occurs after a SQL script
execution.
Occurs when taking a
specific action before
executing the current SQL
statement is needed.
Occurs when SQL Server
raises an error.

AfterExecute

BeforeExecute

OnErrorSee Also
TDAScript Class
TDAScript Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.4.1 AfterExecute Event

Occurs after a SQL script execution.

Class
TDAScript

Syntaxproperty AfterExecute: TAfterStatementExecuteEvent;Remarks
Occurs after a SQL script has been executed.

See Also
Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.4.2 BeforeExecute Event

Occurs when taking a specific action before executing the current SQL statement is needed.

Class
TDAScript© 2019 Devart

248

SQL Server Data Access Components

Syntaxproperty BeforeExecute: TBeforeStatementExecuteEvent;Remarks
Write the BeforeExecute event handler to take specific action before executing the current
SQL statement. SQL holds text of the current SQL statement. Write SQL to change thestatement that will be executed. Set Omit to True to skip statement execution.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.1.4.3 OnError Event

Occurs when SQL Server raises an error.

Class
TDAScript

Syntaxproperty OnError: TOnErrorEvent;Remarks
Occurs when SQL Server raises an error.
Action indicates the action to take when the OnError handler exits. On entry into the handler,
Action is always set to eaFail.

See Also
ErrorOffset© 1997-2019
Devart. All Rights
Reserved.
5.8.1.2

Request Support

DAC Forum

Provide Feedback

TDAStatement ClassThis class has attributes and methods for controlling single SQL statement of a script.
For a list of all members of this type, see TDAStatement members.

Unit
DAScript© 2019 DevartReference

249

Syntax
TDAStatement = class(TCollectionItem);Remarks
TDAScript contains SQL statements, represented as TDAStatement objects. The
TDAStatement class has attributes and methods for controlling single SQL statement of ascript.

See Also
TDAScript
TDAStatements© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.1 Members

TDAStatement class overview.

Properties
Name
EndLineEndOffset
EndPosOmit
ParamsScriptSQLStartLine© 2019 Devart

Description
Used to determine thenumber of the last statement
line in a script.
Used to get the offset in thelast line of the statement.
Used to get the end positionof the statement in a script.
Used to avoid execution of astatement.
Contains parasmeters for an
SQL statement.
Used to determine the
TDAScript object the SQLStatement belongs to.
Used to get or set the text ofan SQL statement.
Used to determine thenumber of the first statement
line in a script.

250

SQL Server Data Access Components

Used to get the offset in thefirst line of a statement.
Used to get the start positionof the statement in a script.

StartOffset
StartPos

Methods
Name
Execute© 1997-2019
Devart. All Rights
Reserved.

Description
Executes a statement.
Request Support

DAC Forum

Provide Feedback

5.8.1.2.2 Properties

Properties of the TDAStatement class.
For a complete list of the TDAStatement class members, see the TDAStatement Members
topic.

PublicName
EndLineEndOffset
EndPosOmit
ParamsScriptSQLStartLineStartOffset

Description
Used to determine thenumber of the last statement
line in a script.
Used to get the offset in thelast line of the statement.
Used to get the end positionof the statement in a script.
Used to avoid execution of astatement.
Contains parasmeters for an
SQL statement.
Used to determine the
TDAScript object the SQLStatement belongs to.
Used to get or set the text ofan SQL statement.
Used to determine thenumber of the first statement
line in a script.
Used to get the offset in thefirst line of a statement.
© 2019 DevartReference

251

Used to get the start positionof the statement in a script.

StartPos

See Also
TDAStatement Class
TDAStatement Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.1 EndLine Property

Used to determine the number of the last statement line in a script.

Class
TDAStatement

Syntaxproperty EndLine: integer;

Remarks
Use the EndLine property to determine the number of the last statement line in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.2 EndOffset Property

Used to get the offset in the last line of the statement.

Class
TDAStatement

Syntaxproperty EndOffset: integer;

Remarks
Use the EndOffset property to get the offset in the last line of the statement.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

252

SQL Server Data Access Components

Reserved.
5.8.1.2.2.3 EndPos Property

Used to get the end position of the statement in a script.

Class
TDAStatement

Syntaxproperty EndPos: integer;

Remarks
Use the EndPos property to get the end position of the statement (the position of the last
character in the statement) in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.4 Omit Property

Used to avoid execution of a statement.

Class
TDAStatement

Syntaxproperty Omit: boolean;

Remarks
Set the Omit property to True to avoid execution of a statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.5 Params Property

Contains parasmeters for an SQL statement.

Class
TDAStatement© 2019 DevartReference

253

Syntaxproperty Params: TDAParams;

Remarks
Contains parameters for an SQL statement.
Access Params at runtime to view and set parameter names, values, and data types
dynamically. Params is a zero-based array of parameter records. Index specifies the arrayelement to access.

See Also
TDAParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.6 Script Property

Used to determine the TDAScript object the SQL Statement belongs to.

Class
TDAStatement

Syntaxproperty Script: TDAScript;

Remarks
Use the Script property to determine the TDAScript object the SQL Statement belongs to.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.8.1.2.2.7 SQL Property

Used to get or set the text of an SQL statement.

Class
TDAStatement

Syntax© 2019 Devart

Provide Feedback

254

SQL Server Data Access Components

property SQL: string;

Remarks
Use the SQL property to get or set the text of an SQL statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.8 StartLine Property

Used to determine the number of the first statement line in a script.

Class
TDAStatement

Syntaxproperty StartLine: integer;

Remarks
Use the StartLine property to determine the number of the first statement line in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.2.9 StartOffset Property

Used to get the offset in the first line of a statement.

Class
TDAStatement

Syntaxproperty StartOffset: integer;

Remarks
Use the StartOffset property to get the offset in the first line of a statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

255

5.8.1.2.2.10 StartPos Property

Used to get the start position of the statement in a script.

Class
TDAStatement

Syntaxproperty StartPos: integer;

Remarks
Use the StartPos property to get the start position of the statement (the position of the firststatement character) in a script.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.2.3 Methods

Methods of the TDAStatement class.
For a complete list of the TDAStatement class members, see the TDAStatement Members
topic.

PublicName
ExecuteDescription
Executes a statement.

See Also
TDAStatement Class
TDAStatement Class Members© 1997-2019
Devart. All Rights
Reserved.
5.8.1.2.3.1 Execute Method

Executes a statement.

Class
TDAStatement© 2019 Devart

Request Support

DAC Forum

Provide Feedback

256

SQL Server Data Access Components

Syntax
procedure Execute;

Remarks
Use the Execute method to execute a statement.

© 1997-2019
Devart. All Rights
Reserved.
5.8.1.3

Request Support

DAC Forum

Provide Feedback

TDAStatements Class

Holds a collection of TDAStatement objects.
For a list of all members of this type, see TDAStatements members.

Unit
DAScript

Syntax
TDAStatements = class(TCollection);

Remarks
Each TDAStatements holds a collection of TDAStatement objects. TDAStatements maintains
an index of the statements in its Items array. The Count property contains the number ofstatements in the collection. Use TDAStatements class to manipulate script SQL statements.

See Also
TDAScript
TDAStatement© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.3.1 Members

TDAStatements class overview.

Properties
Name

Description© 2019 DevartReference

Used to access separate
script statements.

Items© 1997-2019
Devart. All Rights
Reserved.

257

Request Support

DAC Forum

Provide Feedback

5.8.1.3.2 Properties

Properties of the TDAStatements class.
For a complete list of the TDAStatements class members, see the TDAStatements
Members topic.

PublicName

Description
Used to access separate
script statements.

Items

See Also
TDAStatements Class
TDAStatements Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.8.1.3.2.1 Items Property(Indexer)

Used to access separate script statements.

Class
TDAStatements

Syntaxproperty Items[Index: Integer]: TDAStatement; default;
Parameters
Index
Holds the index value.

Remarks
Use the Items property to access individual script statements. The value of the Index© 2019 Devart

258

SQL Server Data Access Components

parameter corresponds to the Index property of TDAStatement.

See Also
TDAStatement© 1997-2019
Devart. All Rights
Reserved.
5.8.2

Request Support

DAC Forum

Provide Feedback

Types
Types in the DAScript unit.

Types
Name

Description
This type is used for the
TDAScript.AfterExecute
event.
This type is used for the
TDAScript.BeforeExecute
event.
This type is used for the
TDAScript.OnError event.

TAfterStatementExecuteEvent

TBeforeStatementExecuteEvent
TOnErrorEvent© 1997-2019
Devart. All Rights
Reserved.
5.8.2.1

Request Support

DAC Forum

Provide Feedback

TAfterStatementExecuteEvent Procedure ReferenceThis type is used for the TDAScript.AfterExecute event.

Unit
DAScript

SyntaxTAfterStatementExecuteEvent = procedure (Sender: TObject; SQL:
string) of object;Parameters
SenderAn object that raised the event.
SQL
Holds the passed SQL statement.
© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.
5.8.2.2

Request Support

DAC Forum

259

Provide Feedback

TBeforeStatementExecuteEvent Procedure ReferenceThis type is used for the TDAScript.BeforeExecute event.

Unit
DAScript

SyntaxTBeforeStatementExecuteEvent = procedure (Sender: TObject; var
SQL: string; var Omit: boolean) of object;Parameters
SenderAn object that raised the event.
SQL
Holds the passed SQL statement.
Omit
True, if the statement execution should be skipped.

© 1997-2019
Devart. All Rights
Reserved.
5.8.2.3

Request Support

DAC Forum

Provide Feedback

TOnErrorEvent Procedure ReferenceThis type is used for the TDAScript.OnError event.

Unit
DAScript

SyntaxTOnErrorEvent = procedure (Sender: TObject; E: Exception; SQL:
string; var Action: TErrorAction) of object;Parameters
SenderAn object that raised the event.
E
The error code.

© 2019 Devart

260

SQL Server Data Access Components

SQL
Holds the passed SQL statement.
ActionThe action to take when the OnError handler exits.

© 1997-2019
Devart. All Rights
Reserved.
5.8.3

Request Support

DAC Forum

Provide Feedback

Enumerations
Enumerations in the DAScript unit.

Enumerations
Name

Description
Indicates the action to takewhen the OnError handler
exits.

TErrorAction© 1997-2019
Devart. All Rights
Reserved.
5.8.3.1

Request Support

DAC Forum

Provide Feedback

TErrorAction Enumeration

Indicates the action to take when the OnError handler exits.

Unit
DAScript

SyntaxTErrorAction = (eaAbort, eaFail, eaException, eaContinue);

ValuesValue
eaAborteaContinue
eaException
eaFail© 1997-2019
Devart. All Rights

Meaning
Abort execution without displaying an error message.
Continue execution.
In Delphi 6 and higher exception is handled by the
Application.HandleException method.
Abort execution and display an error message.
Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

261

Reserved.

5.9

DASQLMonitor
This unit contains the base class for the TMSSQLMonitor component.

ClassesName

Description
A base class that introduces
properties and methods tomonitor dynamic SQL
execution in databaseapplications interactively.
This class holds options for
dbMonitor.

TCustomDASQLMonitor

TDBMonitorOptions

Types
Name

Description
Represents the set of
TDATraceFlag.
Represents the set of
TMonitorOption.
This type is used for the
TCustomDASQLMonitor.On
SQL event.

TDATraceFlags
TMonitorOptions
TOnSQLEvent

Enumerations
Name

Description
Use TraceFlags to specify
which database operations
the monitor should track in
an application at runtime.
Used to define where
information from
SQLMonitor will bedispalyed.

TDATraceFlag

TMonitorOption© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

262

5.9.1

SQL Server Data Access Components

ClassesClasses in the DASQLMonitor unit.

ClassesName

Description
A base class that introduces
properties and methods tomonitor dynamic SQL
execution in databaseapplications interactively.
This class holds options for
dbMonitor.

TCustomDASQLMonitor

TDBMonitorOptions© 1997-2019
Devart. All Rights
Reserved.
5.9.1.1

Request Support

DAC Forum

Provide Feedback

TCustomDASQLMonitor ClassA base class that introduces properties and methods to monitor dynamic SQL execution in
database applications interactively.
For a list of all members of this type, see TCustomDASQLMonitor members.

Unit
DASQLMonitor

SyntaxTCustomDASQLMonitor = class(TComponent);

Remarks
TCustomDASQLMonitor is a base class that introduces properties and methods to monitor
dynamic SQL execution in database applications interactively. TCustomDASQLMonitor
provides two ways of displaying debug information. It monitors either by dialog window or by
Borland's proprietary SQL Monitor. Furthermore to receive debug information use theTCustomDASQLMonitor.OnSQL event.
In applications use descendants of TCustomDASQLMonitor.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference263

5.9.1.1.1 Members

TCustomDASQLMonitor class overview.

Properties
Name

Description
Used to activate monitoringof SQL.
Used to set options for
dbMonitor.
Used to include the desired
properties for
TCustomDASQLMonitor.
Used to specify which
database operations themonitor should track in an
application at runtime.

ActiveDBMonitorOptions
Options

TraceFlags

EventsName

Description
Occurs when tracing of SQL
activity on database
components is needed.

OnSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.2 Properties

Properties of the TCustomDASQLMonitor class.
For a complete list of the TCustomDASQLMonitor class members, see theTCustomDASQLMonitor Members topic.

PublicName
ActiveDBMonitorOptions
Options© 2019 Devart

Description
Used to activate monitoringof SQL.
Used to set options for
dbMonitor.
Used to include the desired
properties for

264

SQL Server Data Access Components

TCustomDASQLMonitor.
Used to specify which
database operations themonitor should track in an
application at runtime.

TraceFlags

See Also
TCustomDASQLMonitor Class
TCustomDASQLMonitor Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.2.1 Active Property

Used to activate monitoring of SQL.

Class
TCustomDASQLMonitor

Syntaxproperty Active: boolean default True;

Remarks
Set the Active property to True to activate monitoring of SQL.

See Also
OnSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.2.2 DBMonitorOptions Property

Used to set options for dbMonitor.

Class
TCustomDASQLMonitor

Syntax© 2019 DevartReference

265

property DBMonitorOptions: TDBMonitorOptions;Remarks
Use DBMonitorOptions to set options for dbMonitor.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.2.3 Options Property

Used to include the desired properties for TCustomDASQLMonitor.

Class
TCustomDASQLMonitor

Syntaxproperty Options: TMonitorOptions default [moDialog,
moSQLMonitor, moDBMonitor, moCustom];Remarks
Set Options to include the desired properties for TCustomDASQLMonitor.

See Also
OnSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.2.4 TraceFlags Property

Used to specify which database operations the monitor should track in an application at
runtime.

Class
TCustomDASQLMonitor

Syntaxproperty TraceFlags: TDATraceFlags default [tfQPrepare,tfQExecute, tfError, tfConnect, tfTransact, tfParams, tfMisc];© 2019 Devart

266

SQL Server Data Access Components

Remarks
Use the TraceFlags property to specify which database operations the monitor should track in
an application at runtime.

See Also
OnSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.3 Events

Events of the TCustomDASQLMonitor class.
For a complete list of the TCustomDASQLMonitor class members, see theTCustomDASQLMonitor Members topic.

PublicName

Description
Occurs when tracing of SQL
activity on database
components is needed.

OnSQL

See Also
TCustomDASQLMonitor Class
TCustomDASQLMonitor Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.1.3.1 OnSQL Event

Occurs when tracing of SQL activity on database components is needed.

Class
TCustomDASQLMonitor

Syntaxproperty OnSQL: TOnSQLEvent;Remarks© 2019 DevartReference

267

Write the OnSQL event handler to let an application trace SQL activity on database
components. The Text parameter holds the detected SQL statement. Use the Flag parameterto make selective processing of SQL in the handler body.

See Also
TraceFlags© 1997-2019
Devart. All Rights
Reserved.
5.9.1.2

Request Support

DAC Forum

Provide Feedback

TDBMonitorOptions ClassThis class holds options for dbMonitor.
For a list of all members of this type, see TDBMonitorOptions members.

Unit
DASQLMonitor

SyntaxTDBMonitorOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.1 Members

TDBMonitorOptions class overview.

Properties
Name
Host

Port

ReconnectTimeout

SendTimeout© 2019 Devart

Description
Used to set the host name or
IP address of the computer
where dbMonitor application
runs.
Used to set the port number
for connecting to dbMonitor.
Used to set the minimum
time that should be spent
before reconnecting todbMonitor is allowed.
Used to set timeout for
sending events to268

SQL Server Data Access Components

dbMonitor.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.2 Properties

Properties of the TDBMonitorOptions class.
For a complete list of the TDBMonitorOptions class members, see the TDBMonitorOptions
Members topic.

Published
Name

Description
Used to set the host name or
IP address of the computer
where dbMonitor application
runs.
Used to set the port number
for connecting to dbMonitor.
Used to set the minimum
time that should be spent
before reconnecting todbMonitor is allowed.
Used to set timeout for
sending events todbMonitor.

Host

Port

ReconnectTimeout

SendTimeout

See Also
TDBMonitorOptions Class
TDBMonitorOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.2.1 Host Property

Used to set the host name or IP address of the computer where dbMonitor application runs.

Class
TDBMonitorOptions© 2019 DevartReference

269

Syntaxproperty Host: string;

Remarks
Use the Host property to set the host name or IP address of the computer where dbMonitor
application runs.
dbMonitor supports remote monitoring. You can run dbMonitor on a different computer thanmonitored application runs. In this case you need to set the Host property to thecorresponding computer name.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.2.2 Port Property

Used to set the port number for connecting to dbMonitor.

Class
TDBMonitorOptions

Syntaxproperty Port: integer default DBMonitorPort;

Remarks
Use the Port property to set the port number for connecting to dbMonitor.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.2.3 ReconnectTimeout Property

Used to set the minimum time that should be spent before reconnecting to dbMonitor isallowed.

Class
TDBMonitorOptions

Syntaxproperty ReconnectTimeout: integer default© 2019 Devart

270

SQL Server Data Access Components

DefaultReconnectTimeout;

Remarks
Use the ReconnectTimeout property to set the minimum time (in milliseconds) that should bespent before allowing reconnecting to dbMonitor. If an error occurs when the component
sends an event to dbMonitor (dbMonitor is not running), next events are ignored and thecomponent does not restore the connection until ReconnectTimeout is over.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.9.1.2.2.4 SendTimeout Property

Used to set timeout for sending events to dbMonitor.

Class
TDBMonitorOptions

Syntaxproperty SendTimeout: integer default DefaultSendTimeout;

Remarks
Use the SendTimeout property to set timeout (in milliseconds) for sending events todbMonitor. If dbMonitor does not respond in the specified timeout, event is ignored.

© 1997-2019
Devart. All Rights
Reserved.
5.9.2

Request Support

DAC Forum

Provide Feedback

Types
Types in the DASQLMonitor unit.

Types
Name
TDATraceFlags
TMonitorOptions
TOnSQLEvent

Description
Represents the set of
TDATraceFlag.
Represents the set of
TMonitorOption.
This type is used for the
TCustomDASQLMonitor.On© 2019 DevartReference271

SQL event.
© 1997-2019
Devart. All Rights
Reserved.
5.9.2.1

Request Support

DAC Forum

Provide Feedback

TDATraceFlags Set

Represents the set of TDATraceFlag.

Unit
DASQLMonitor

SyntaxTDATraceFlags = set of TDATraceFlag;© 1997-2019
Devart. All Rights
Reserved.
5.9.2.2

Request Support

DAC Forum

Provide Feedback

TMonitorOptions Set

Represents the set of TMonitorOption.

Unit
DASQLMonitor

Syntax
TMonitorOptions = set of TMonitorOption;© 1997-2019
Devart. All Rights
Reserved.
5.9.2.3

Request Support

DAC Forum

Provide Feedback

TOnSQLEvent Procedure ReferenceThis type is used for the TCustomDASQLMonitor.OnSQL event.

Unit
DASQLMonitor

SyntaxTOnSQLEvent = procedure (Sender: TObject; Text: string; Flag:
TDATraceFlag) of object;© 2019 Devart

272

SQL Server Data Access Components

Parameters
SenderAn object that raised the event.
Text
Holds the detected SQL statement.
Flag
Use the Flag parameter to make selective processing of SQL in the handler body.

© 1997-2019
Devart. All Rights
Reserved.
5.9.3

Request Support

DAC Forum

Provide Feedback

Enumerations
Enumerations in the DASQLMonitor unit.

Enumerations
Name

Description
Use TraceFlags to specify
which database operations
the monitor should track in
an application at runtime.
Used to define where
information from
SQLMonitor will bedispalyed.

TDATraceFlag

TMonitorOption© 1997-2019
Devart. All Rights
Reserved.
5.9.3.1

Request Support

DAC Forum

Provide Feedback

TDATraceFlag Enumeration

Use TraceFlags to specify which database operations the monitor should track in an
application at runtime.

Unit
DASQLMonitor

SyntaxTDATraceFlag = (tfQPrepare, tfQExecute, tfQFetch, tfError, tfStmt,
tfConnect, tfTransact, tfBlob, tfService, tfMisc, tfParams,
tfObjDestroy, tfPool);© 2019 DevartReference

273

ValuesValue
tfBlobtfConnect
tfErrortfMisctfObjDestroy
tfParams
tfPooltfQExecute
tfQFetch
tfQPrepare
tfService
tfStmttfTransact© 1997-2019
Devart. All Rights
Reserved.
5.9.3.2

Meaning
This option is declared for future use.
Establishing a connection.
Errors of query execution.
This option is declared for future use.
Destroying of components.
Representing parameter values for tfQPrepare and tfQExecute.
Connection pool operations.
Execution of the queries.
This option is declared for future use.
Queries preparation.
This option is declared for future use.
This option is declared for future use.
Processing transactions.
Request Support

DAC Forum

Provide Feedback

TMonitorOption Enumeration

Used to define where information from SQLMonitor will be dispalyed.

Unit
DASQLMonitor

Syntax
TMonitorOption = (moDialog, moSQLMonitor, moDBMonitor, moCustom,moHandled);

ValuesValue
moCustommoDBMonitor
moDialog© 2019 Devart

Meaning
Monitoring of SQL for individual components is allowed. Set
Debug properties in SQL-related components to True to let
TCustomDASQLMonitor instance to monitor their behavior. Has
effect when moDialog is included.
Debug information is displayed in DBMonitor.
Debug information is displayed in debug window.

274

SQL Server Data Access Components

moHandled
moSQLMonitor© 1997-2019
Devart. All Rights
Reserved.

5.10

Component handle is included into the event description string.
Debug information is displayed in Borland SQL Monitor.
Request Support

DAC Forum

Provide Feedback

DBAccess
This unit contains base classes for most of the components.

ClassesName
EDAError

TCRDataSource

TCustomConnectDialog
TCustomDAConnection

TCustomDADataSet

TCustomDASQL

TCustomDAUpdateSQLTDACondition
TDAConditions

Description
A base class for exceptions
that are raised when an error
occurs on the server side.
Provides an interface
between a DAC dataset
components and data-aware
controls on a form.
A base class for the connect
dialog components.
A base class forcomponents used toestablish connections.
Encapsulates general set ofproperties, events, andmethods for working withdata accessed throughvarious database engines.
A base class forcomponents executing SQL
statements that do not returnresult sets.
A base class forcomponents that provide
DML statements for more
flexible control over data
modifications.
Represents a condition fromthe TDAConditions list.
Holds a collection of
TDACondition objects.

© 2019 DevartReference

TDAConnectionOptions

TDADataSetOptions

TDAEncryption
TDAMapRule

TDAMapRules

TDAMetaData

TDAParam

TDAParams

TDATransaction
TMacroTMacros

TPoolingOptions

TSmartFetchOptions© 2019 Devart

275This class allows setting up
the behaviour of the
TDAConnection class.
This class allows setting up
the behaviour of the
TDADataSet class.
Used to specify the optionsof the data encryption in adataset.
Class that formes rules for
Data Type Mapping.
Used for adding rules for
DataSet fields mapping withboth identifying by fieldname and by field type andDelphi field types.
A class for retrieving
metainformation of thespecified database objects
in the form of dataset.
A class that forms objects torepresent the values of theparameters set.
This class is used to
manage a list of TDAParamobjects for an object thatuses field parameters.
A base class that
implements functionality forcontrolling transactions.
Object that represents thevalue of a macro.
Controls a list of TMacroobjects for the
TCustomDASQL.Macros orTCustomDADataSet
components.
This class allows setting up
the behaviour of theconnection pool.
Smart fetch options areused to set up the behaviorof the SmartFetch mode.

276

SQL Server Data Access Components

Types
Name
TAfterExecuteEvent

TAfterFetchEvent

TBeforeFetchEvent

TConnectionLostEvent

TDAConnectionErrorEvent

TDATransactionErrorEvent
TRefreshOptions

TUpdateExecuteEvent

Description
This type is used for the
TCustomDADataSet.AfterE
xecute andTCustomDASQL.AfterExecu
te events.
This type is used for the
TCustomDADataSet.AfterF
etch event.
This type is used for the
TCustomDADataSet.Before
Fetch event.
This type is used for the
TCustomDAConnection.On
ConnectionLost event.
This type is used for the
TCustomDAConnection.On
Error event.
This type is used for the
TDATransaction.OnError
event.
Represents the set of
TRefreshOption.
This type is used for the
TCustomDADataSet.AfterU
pdateExecute andTCustomDADataSet.Before
UpdateExecute events.

Enumerations
Name
TLabelSet
TRefreshOption
TRetryMode

Description
Sets the languauge of labelsin the connect dialog.
Indicates when the editing
record will be refreshed.
Specifies the application
behavior when connection islost.

© 2019 DevartReference

277

Variables
Name

Description
After assigning SQL text andmodifying it by AddWhere,
DeleteWhere, and
SetOrderBy, all subsequentchanges of the SQL property
will not be reflected in the
BaseSQL property.
When set to True allows
data access components tochange screen cursor for the
execution time.
The value of theTCustomDADataSet.BaseSQL property is used tocomplete the refresh SQL
statement, if the manuallyassigned
TCustomDAUpdateSQL.Ref
reshSQL property contains
only WHERE clause.

BaseSQLOldBehavior

ChangeCursor

SQLGeneratorCompatibility© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1 Classes
Classes in the DBAccess unit.

ClassesName
EDAError

TCRDataSource

TCustomConnectDialog
TCustomDAConnection© 2019 Devart

Description
A base class for exceptions
that are raised when an error
occurs on the server side.
Provides an interface
between a DAC dataset
components and data-aware
controls on a form.
A base class for the connect
dialog components.
A base class for

278

SQL Server Data Access Components

TCustomDADataSet

TCustomDASQL

TCustomDAUpdateSQLTDACondition
TDAConditions
TDAConnectionOptions

TDADataSetOptions

TDAEncryption
TDAMapRule

TDAMapRules

TDAMetaData

TDAParam
TDAParamscomponents used toestablish connections.
Encapsulates general set ofproperties, events, andmethods for working withdata accessed throughvarious database engines.
A base class forcomponents executing SQL
statements that do not returnresult sets.
A base class forcomponents that provide
DML statements for more
flexible control over data
modifications.
Represents a condition fromthe TDAConditions list.
Holds a collection of
TDACondition objects.
This class allows setting up
the behaviour of the
TDAConnection class.
This class allows setting up
the behaviour of the
TDADataSet class.
Used to specify the optionsof the data encryption in adataset.
Class that formes rules for
Data Type Mapping.
Used for adding rules for
DataSet fields mapping withboth identifying by fieldname and by field type andDelphi field types.
A class for retrieving
metainformation of thespecified database objects
in the form of dataset.
A class that forms objects torepresent the values of theparameters set.
This class is used to© 2019 DevartReference

manage a list of TDAParamobjects for an object thatuses field parameters.
A base class that
implements functionality forcontrolling transactions.
Object that represents thevalue of a macro.
Controls a list of TMacroobjects for the
TCustomDASQL.Macros orTCustomDADataSet
components.
This class allows setting up
the behaviour of theconnection pool.
Smart fetch options areused to set up the behaviorof the SmartFetch mode.

TDATransaction
TMacroTMacros

TPoolingOptions

TSmartFetchOptions© 1997-2019
Devart. All Rights
Reserved.

279

Request Support

DAC Forum

Provide Feedback

5.10.1.1 EDAError ClassA base class for exceptions that are raised when an error occurs on the server side.
For a list of all members of this type, see EDAError members.

Unit
DBAccess

SyntaxEDAError = class(EDatabaseError);

Remarks
EDAError is a base class for exceptions that are raised when an error occurs on the serverside.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

280

SQL Server Data Access Components

5.10.1.1.1 Members

EDAError class overview.

Properties
Name

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.

Component
ErrorCode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.1.2 Properties

Properties of the EDAError class.
For a complete list of the EDAError class members, see the EDAError Members topic.

PublicName

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.

Component
ErrorCode

See Also
EDAError ClassEDAError Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.1.2.1 Component Property

Contains the component that caused the error.

Class
EDAError

Syntax© 2019 DevartReference281

property Component: TObject;

Remarks
The Component property contains the component that caused the error.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.1.2.2 ErrorCode Property

Determines the error code returned by the server.

Class
EDAError

Syntaxproperty ErrorCode: integer;

Remarks
Use the ErrorCode property to determine the error code returned by SQL Server. This value
is always positive.
In SQL Server it's preferable to use EOLEDBError.OLEDBErrorCode and
EMSError.MSSQLErrorCode instead of EDAError.ErrorCode.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.2 TCRDataSource Class

Provides an interface between a DAC dataset components and data-aware controls on aform.
For a list of all members of this type, see TCRDataSource members.

Unit
DBAccess

SyntaxTCRDataSource = class(TDataSource);

Remarks© 2019 Devart

282

SQL Server Data Access Components

TCRDataSource provides an interface between a DAC dataset components and data-aware
controls on a form.
TCRDataSource inherits its functionality directly from the TDataSource component.
At design time assign individual data-aware components' DataSource properties from theirdrop-down listboxes.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.10.1.2.1 Members

TCRDataSource class overview.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.3 TCustomConnectDialog ClassA base class for the connect dialog components.
For a list of all members of this type, see TCustomConnectDialog members.

Unit
DBAccess

SyntaxTCustomConnectDialog = class(TComponent);

Remarks
TCustomConnectDialog is a base class for the connect dialog components. It provides
functionality to show a dialog box where user can edit username, password and server namebefore connecting to a database. You can customize captions of buttons and labels by theirproperties.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.1 Members

TCustomConnectDialog class overview.

Properties© 2019 DevartReference

Name

283

Description
Used to specify the label for
the Cancel button.
Used to set the caption of
dialog box.
Used to specify the label for
the Connect button.
Used to specify the class ofthe form that will be
displayed to enter login
information.
Used to set the language ofbuttons and labels captions.
Used to specify a prompt for
password edit.
Used to indicate the numberof retries of failed
connections.
Used for the password to be
displayed in ConnectDialog
in asterisks.
Used to specify a prompt forthe server name edit.
Used to specify whether thelogin information should be
kept in system registry after
a connection wasestablished.
Used to specify a prompt forusername edit.

CancelButton
CaptionConnectButton

DialogClass

LabelSet
PasswordLabel
Retries

SavePassword
ServerLabelStoreLogInfo

UsernameLabel

Methods
Name

Description
Displays the connect dialog
and calls the connection's
Connect method when user
clicks the Connect button.
Retrieves a list of available
server names.

Execute

GetServerList© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

284

SQL Server Data Access Components

5.10.1.3.2 Properties

Properties of the TCustomConnectDialog class.
For a complete list of the TCustomConnectDialog class members, see theTCustomConnectDialog Members topic.

PublicName

Description
Used to specify the label for
the Cancel button.
Used to set the caption of
dialog box.
Used to specify the label for
the Connect button.
Used to specify the class ofthe form that will be
displayed to enter login
information.
Used to set the language ofbuttons and labels captions.
Used to specify a prompt for
password edit.
Used to indicate the numberof retries of failed
connections.
Used for the password to be
displayed in ConnectDialog
in asterisks.
Used to specify a prompt forthe server name edit.
Used to specify whether thelogin information should be
kept in system registry after
a connection wasestablished.
Used to specify a prompt forusername edit.

CancelButton
CaptionConnectButton

DialogClass

LabelSet
PasswordLabel
Retries

SavePassword
ServerLabelStoreLogInfo

UsernameLabel

See Also
TCustomConnectDialog Class
TCustomConnectDialog Class Members© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference285

Devart. All Rights
Reserved.
5.10.1.3.2.1 CancelButton Property

Used to specify the label for the Cancel button.

Class
TCustomConnectDialog

Syntaxproperty CancelButton: string;

Remarks
Use the CancelButton property to specify the label for the Cancel button.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.2 Caption Property

Used to set the caption of dialog box.

Class
TCustomConnectDialog

Syntaxproperty Caption: string;

Remarks
Use the Caption property to set the caption of dialog box.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.3.2.3 ConnectButton Property

Used to specify the label for the Connect button.

Class
TCustomConnectDialog© 2019 Devart

Provide Feedback

286

SQL Server Data Access Components

Syntaxproperty ConnectButton: string;

Remarks
Use the ConnectButton property to specify the label for the Connect button.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.4 DialogClass Property

Used to specify the class of the form that will be displayed to enter login information.

Class
TCustomConnectDialog

Syntaxproperty DialogClass: string;

Remarks
Use the DialogClass property to specify the class of the form that will be displayed to enter
login information. When this property is blank, TCustomConnectDialog uses the default form TConnectForm. You can write your own login form to enter login information and assign its
class name to the DialogClass property. Each login form must have ConnectDialog:
TCustomConnectDialog published property to access connection information. For details see
the implementation of the connect form which sources are in the Lib subdirectory of theSDAC installation directory.

See Also
GetServerList© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.5 LabelSet Property

Used to set the language of buttons and labels captions.

Class© 2019 DevartReference

287

TCustomConnectDialog

Syntaxproperty LabelSet: TLabelSet default lsEnglish;

Remarks
Use the LabelSet property to set the language of labels and buttons captions.
The default value is lsEnglish.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.6 Passw ordLabel Property

Used to specify a prompt for password edit.

Class
TCustomConnectDialog

Syntaxproperty PasswordLabel: string;

Remarks
Use the PasswordLabel property to specify a prompt for password edit.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.7 Retries Property

Used to indicate the number of retries of failed connections.

Class
TCustomConnectDialog

Syntaxproperty Retries: word default 3;

Remarks
Use the Retries property to determine the number of retries of failed connections.
© 2019 Devart

288

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.8 SavePassw ord Property

Used for the password to be displayed in ConnectDialog in asterisks.

Class
TCustomConnectDialog

Syntaxproperty SavePassword: boolean default False;

Remarks
If True, and the Password property of the connection instance is assigned, the password inConnectDialog is displayed in asterisks.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.9 ServerLabel Property

Used to specify a prompt for the server name edit.

Class
TCustomConnectDialog

Syntaxproperty ServerLabel: string;

Remarks
Use the ServerLabel property to specify a prompt for the server name edit.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.10 StoreLogInfo Property

Used to specify whether the login information should be kept in system registry after aconnection was established.

© 2019 DevartReference

289

Class
TCustomConnectDialog

Syntaxproperty StoreLogInfo: boolean default True;

Remarks
Use the StoreLogInfo property to specify whether to keep login information in system registry
after a connection was established using provided username, password and servername.
Set this property to True to store login information.
The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.2.11 UsernameLabel Property

Used to specify a prompt for username edit.

Class
TCustomConnectDialog

Syntaxproperty UsernameLabel: string;

Remarks
Use the UsernameLabel property to specify a prompt for username edit.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.3 Methods

Methods of the TCustomConnectDialog class.
For a complete list of the TCustomConnectDialog class members, see theTCustomConnectDialog Members topic.

Public© 2019 Devart

290

SQL Server Data Access Components

Name

Description
Displays the connect dialog
and calls the connection's
Connect method when user
clicks the Connect button.
Retrieves a list of available
server names.

Execute

GetServerList

See Also
TCustomConnectDialog Class
TCustomConnectDialog Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.3.1 Execute Method

Displays the connect dialog and calls the connection's Connect method when user clicks theConnect button.

Class
TCustomConnectDialog

Syntaxfunction Execute: boolean; virtual;
Return Value
True, if connected.

Remarks
Displays the connect dialog and calls the connection's Connect method when user clicks theConnect button. Returns True if connected. If user clicks Cancel, Execute returns False.
In the case of failed connection Execute offers to connect repeat Retries times.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.3.3.2 GetServerList Method

Retrieves a list of available server names.

Class© 2019 DevartReference

291

TCustomConnectDialog

Syntax
procedure GetServerList(List: TStrings); virtual;Parameters
List
Holds a list of available server names.

Remarks
Call the GetServerList method to retrieve a list of available server names. It is particularly
relevant for writing custom login form.

See Also
DialogClass© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4 TCustomDAConnection ClassA base class for components used to establish connections.
For a list of all members of this type, see TCustomDAConnection members.

Unit
DBAccess

SyntaxTCustomDAConnection = class(TCustomConnection);

Remarks
TCustomDAConnection is a base class for components that establish connection with
database, provide customised login support, and perform transaction control.
Do not create instances of TCustomDAConnection. To add a component that represents a
connection to a source of data, use descendants of the TCustomDAConnection class.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

292

SQL Server Data Access Components

5.10.1.4.1 Members

TCustomDAConnection class overview.

Properties
Name
ConnectDialog

ConnectString

ConvertEOL
InTransaction

LoginPrompt

Options
Password
Pooling
PoolingOptions
ServerUsername

Description
Allows to link a
TCustomConnectDialog
component.
Used to specify theconnection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
breaks in string fields andparameters.
Indicates whether thetransaction is active.
Specifies whether a login
dialog appears immediately
before opening a newconnection.
Specifies the connection
behavior.
Serves to supply apassword for login.
Enables or disables using
connection pool.
Specifies the behaviour ofconnection pool.
Serves to supply the server
name for login.
Used to supply a user namefor login.

Methods
Name

CommitDescription
Overloaded. Applies
changes in datasets.
Commits current transaction.

Connect

Establishes a connection to

ApplyUpdates© 2019 DevartReference

CreateSQL
Disconnect
ExecProc

ExecProcEx
ExecSQLExecSQLEx

GetDatabaseNames
GetKeyFieldNames
GetStoredProcNames
GetTableNames

MonitorMessage

Ping
RemoveFromPool

Rollback
StartTransaction

the server.
Creates a component for
queries execution.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.
Provides a list of available
key field names.
Returns a list of stored
procedures from the server.
Provides a list of available
tables names.
Sends a specified message
through theTCustomDASQLMonitor
component.
Used to check state ofconnection to the server.
Marks the connection thatshould not be returned to thepool after disconnect.
Discards all current datachanges and ends
transaction.
Begins a new usertransaction.

EventsName© 2019 Devart

293

Description

294

SQL Server Data Access Components

This event occurs whenconnection was lost.
This event occurs when anerror has arisen in theconnection.

OnConnectionLost
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2 Properties

Properties of the TCustomDAConnection class.
For a complete list of the TCustomDAConnection class members, see theTCustomDAConnection Members topic.

PublicName
ConnectDialog

ConnectString

ConvertEOL
InTransaction

LoginPrompt

Options
Password
Pooling
PoolingOptions
ServerDescription
Allows to link a
TCustomConnectDialog
component.
Used to specify theconnection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
breaks in string fields andparameters.
Indicates whether thetransaction is active.
Specifies whether a login
dialog appears immediately
before opening a newconnection.
Specifies the connection
behavior.
Serves to supply apassword for login.
Enables or disables using
connection pool.
Specifies the behaviour ofconnection pool.
Serves to supply the server
name for login.
© 2019 DevartReference

295

Used to supply a user namefor login.

Username

See Also
TCustomDAConnection Class
TCustomDAConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.1 ConnectDialog Property

Allows to link a TCustomConnectDialog component.

Class
TCustomDAConnection

Syntaxproperty ConnectDialog: TCustomConnectDialog;

Remarks
Use the ConnectDialog property to assign to connection a TCustomConnectDialog
component.

See Also
TCustomConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.2 ConnectString Property

Used to specify the connection information, such as: UserName, Password, Server, etc.

Class
TCustomDAConnection

Syntaxproperty ConnectString: string stored False;© 2019 Devart

296

SQL Server Data Access Components

Remarks
SDAC recognizes an ODBC-like syntax in provider string property values. Within the string,elements are delimited by using a semicolon. Each element consists of a keyword, an equal
sign character, and the value passed on initialization. For example:
Server=London1;User ID=nancyd

Connection parameters
The following connection parameters can be used to customize connection:

Parameter Name
LoginPrompt
Pooling
ConnectionLifeTime

MaxPoolSize

MinPoolSize
Validate Connection
Server
Database (If prCompact)
Username
PasswordPort
ConnectionTimeout
ProviderForceCreateDatabase

Description
Specifies whether a login dialog appears
immediately before opening a newconnection.
Enables or disables using connection pool.
Used to specify the maximum time during
which an opened connection can be usedby connection pool.
Used to specify the maximum number ofconnections that can be opened inconnection pool.
Used to specify the minimum number ofconnections that can be opened inconnection pool.
Used for a connection to be validated when
it is returned from the pool.
Serves to supply the server name for login.
Used to specify the database name that isa default source of data for SQL queries
once a connection is established.
Used to supply a user name for login.
Serves to supply a password for login.
Used to specify the port number for theconnection.
Used to specify the amount of time before
an attempt to make a connection isconsidered unsuccessful.
Used to specify a provider from the list of
supported providers.
Used to force TMSConnection to create a
new database before opening aconnection, if the database is not exists.
© 2019 DevartReference

Encrypt
Integrated Security, Trusted_Connection
Language
PersistSecurityInfo

AutoTranslate

NetworkLibrary

ApplicationName
WorkstationID
PacketSize
InitialFileName
MultipleActiveResultSets
FailoverPartner
TrustServerCertificate
ApplicationIntent

297

Specifies if data should be encrypted
before sending it over the network.
Used to specify the authentication service
used by the database server to identify auser.
Specifies the SQL Server language name.
Used to allow the data source object topersist sensitive authentication informationsuch as a password along with otherauthentication information.
Used to translate character strings sent
between the client and server by converting
through Unicode.
Specifies the name of the Net-Library(DLL) used to communicate with an
instance of SQL Server.
The name of a client application. The
default value is the name of the executable
file of your application.
A string identifying the workstation.
Network packet size in bytes.
Specifies the name of the main database
file.
Enables support for the Multiple Active
Result Sets (MARS) technology.
Specifies the SQL Server name to which
SQL Native Client will reconnect when afailover of the principal SQL Server occurs.
Used to enable traffic encryption without
validation.
Used to specify the application workload
type when connecting to a server.

See Also
Password
Username
ServerConnect© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

298

SQL Server Data Access Components

5.10.1.4.2.3 ConvertEOL Property

Allows customizing line breaks in string fields and parameters.

Class
TCustomDAConnection

Syntaxproperty ConvertEOL: boolean default False;

Remarks
Affects the line break behavior in string fields and parameters. When fetching strings(including the TEXT fields) with ConvertEOL = True, dataset converts their line breaks fromthe LF to CRLF form. And when posting strings to server with ConvertEOL turned on, theirline breaks are converted from CRLF to LF form. By default, strings are not converted.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.4 InTransaction Property

Indicates whether the transaction is active.

Class
TCustomDAConnection

Syntaxproperty InTransaction: boolean;

Remarks
Examine the InTransaction property at runtime to determine whether user transaction iscurrently in progress. In other words InTransaction is set to True when user explicitly calls
StartTransaction. Calling Commit or Rollback sets InTransaction to False. The value of the
InTransaction property cannot be changed directly.

See Also
StartTransaction
CommitRollback© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

299

Provide Feedback

5.10.1.4.2.5 LoginPrompt Property

Specifies whether a login dialog appears immediately before opening a new connection.

Class
TCustomDAConnection

Syntaxproperty LoginPrompt default DefValLoginPrompt;

Remarks
Specifies whether a login dialog appears immediately before opening a new connection. If
ConnectDialog is not specified, the default connect dialog will be shown. The connect dialog
will appear only if the SdacVcl unit appears to the uses clause.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.6 Options Property

Specifies the connection behavior.

Class
TCustomDAConnection

Syntaxproperty Options: TDAConnectionOptions;Remarks
Set the properties of Options to specify the behaviour of the connection.
Descriptions of all options are in the table below.

Option Name
AllowImplicitConnect
DefaultSortType© 2019 Devart

Description
Specifies whether to allow or not implicit
connection opening.
Used to determine the default type of local
sorting for string fields. It is used when a

300

SQL Server Data Access Components

DisconnectedMode

KeepDesignConnected

LocalFailover

sort type is not specified explicitly after thefield name in the
TMemDataSet.IndexFieldNames property
of a dataset.
Used to open a connection only whenneeded for performing a server call andcloses after performing the operation.
Used to prevent an application fromestablishing a connection at the time ofstartup.
If True, the OnConnectionLost event occurs
and a failover operation can be performed
after connection breaks.

See Also
Disconnected Mode
Working in an Unstable Network© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.7 Passw ord Property

Serves to supply a password for login.

Class
TCustomDAConnection

Syntaxproperty Password: string stored False;

Remarks
Use the Password property to supply a password to handle server's request for a login.
Warning: Storing hard-coded user name and password entries as property values or in codefor the OnLogin event handler can compromise server security.

See Also
Username
Server© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

301

Devart. All Rights
Reserved.
5.10.1.4.2.8 Pooling Property

Enables or disables using connection pool.

Class
TCustomDAConnection

Syntaxproperty Pooling: boolean default DefValPooling;

Remarks
Normally, when TCustomDAConnection establishes connection with the server it takes
server memory and time resources for allocating new server connection. For example,
pooling can be very useful when using disconnect mode. If an application has wide user
activity that forces many connect/disconnect operations, it may spend a lot of time on
creating connection and sending requests to the server. TCustomDAConnection has
software pool which stores open connections with identical parameters.
Connection pool uses separate thread that validates the pool every 30 seconds. Poolvalidation consists of checking each connection in the pool. If a connection is broken due to a
network problem or another reason, it is deleted from the pool. The validation procedure
removes also connections that are not used for a long time even if they are valid from thepool.
Set Pooling to True to enable pooling. Specify correct values for PoolingOptions. Twoconnections belong to the same pool if they have identical values for the parameters:
MinPoolSize, MaxPoolSize, Validate, ConnectionLifeTime , Server, Username, Password,
TCustomMSConnection.Database, TCustomMSConnection.IsolationLevel,
TMSConnection.Authentication, QuotedIdentifier, Provider, Language, Encrypt,
PersistSecurityInfo, AutoTranslate, NetworkLibrary, ApplicationName, WorkstationID,
PacketSize.
Note: Using Pooling := True can cause errors with working with temporary tables.

See Also
Username
Password
PoolingOptions
Connection Pooling© 2019 Devart

302

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.9 PoolingOptions Property

Specifies the behaviour of connection pool.

Class
TCustomDAConnection

Syntaxproperty PoolingOptions: TPoolingOptions;Remarks
Set the properties of PoolingOptions to specify the behaviour of connection pool.
Descriptions of all options are in the table below.

Option Name

Description
Used to specify the maximum time during
which an opened connection can be usedby connection pool.
Used to specify the maximum number ofconnections that can be opened inconnection pool.
Used to specify the minimum number ofconnections that can be opened in theconnection pool.
Used for a connection to be validated when
it is returned from the pool.

ConnectionLifetime

MaxPoolSize

MinPoolSize
Validate

See Also
Pooling© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.10 Server Property

Serves to supply the server name for login.

Class© 2019 DevartReference

303

TCustomDAConnection

Syntaxproperty Server: string;

Remarks
Use the Server property to supply server name to handle server's request for a login. If thisproperty is not set, SDAC tries to connect to '(local)'.
If this property is not set, SDAC tries to connect to '(local)'.

See Also
Username
Password© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.2.11 Username Property

Used to supply a user name for login.

Class
TCustomDAConnection

Syntaxproperty Username: string;

Remarks
Use the Username property to supply a user name to handle server's request for login. If thisproperty is not set, SDAC tries to connect with the sa user name.
Warning: Storing hard-coded user name and password entries as property values or in codefor the OnLogin event handler can compromise server security.

See Also
Password
Server© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

304

SQL Server Data Access Components

5.10.1.4.3 Methods

Methods of the TCustomDAConnection class.
For a complete list of the TCustomDAConnection class members, see theTCustomDAConnection Members topic.

PublicName
ApplyUpdates
CommitConnect
CreateSQL
Disconnect
ExecProc

ExecProcEx
ExecSQLExecSQLEx

GetDatabaseNames
GetKeyFieldNames
GetStoredProcNames
GetTableNames

MonitorMessage

Ping

Description
Overloaded. Applies
changes in datasets.
Commits current transaction.
Establishes a connection to
the server.
Creates a component for
queries execution.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.
Provides a list of available
key field names.
Returns a list of stored
procedures from the server.
Provides a list of available
tables names.
Sends a specified message
through theTCustomDASQLMonitor
component.
Used to check state ofconnection to the server.

© 2019 DevartReference

305

Marks the connection thatshould not be returned to thepool after disconnect.
Discards all current datachanges and ends
transaction.
Begins a new usertransaction.

RemoveFromPool

Rollback
StartTransaction

See Also
TCustomDAConnection Class
TCustomDAConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.1 ApplyUpdates Method

Applies changes in datasets.

Class
TCustomDAConnection

Overload List
Name
ApplyUpdates
ApplyUpdates(const DataSets: array ofTCustomDADataSet)© 1997-2019
Request Support
Devart. All Rights
Reserved.

Description
Applies changes from all active datasets.
Applies changes from the specified
datasets.
DAC Forum

Applies changes from all active datasets.

Class
TCustomDAConnection

Syntax
procedure ApplyUpdates; overload; virtual;© 2019 Devart

Provide Feedback

306

SQL Server Data Access Components

Remarks
Call the ApplyUpdates method to write all pending cached updates from all active datasets
attached to this connection to a database or from specific datasets. The ApplyUpdates
method passes cached data to the database for storage, takes care of committing or rollingback transactions, and clearing the cache when the operation is successful.
Using ApplyUpdates for connection is a preferred method of updating datasets rather thancalling each individual dataset's ApplyUpdates method.

See Also
TMemDataSet.CachedUpdates
TMemDataSet.ApplyUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Applies changes from the specified datasets.

Class
TCustomDAConnection

Syntax
procedure ApplyUpdates(const DataSets: array ofTCustomDADataSet); overload; virtual;Parameters
DataSets
A list of datasets changes in which are to be applied.

Remarks
Call the ApplyUpdates method to write all pending cached updates from the specified
datasets. The ApplyUpdates method passes cached data to the database for storage, takes
care of committing or rolling back transactions and clearing the cache when operation is
successful.
Using ApplyUpdates for connection is a preferred method of updating datasets rather thancalling each individual dataset's ApplyUpdates method.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

307

5.10.1.4.3.2 Commit Method

Commits current transaction.

Class
TCustomDAConnection

Syntax
procedure Commit; virtual;

Remarks
Call the Commit method to commit current transaction. On commit server writes
permanently all pending data updates associated with the current transaction to the database
and then ends the transaction. The current transaction is the last transaction started bycalling StartTransaction.

See Also
Rollback
StartTransaction
TCustomMSDataSet.FetchAll© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.3 Connect Method

Establishes a connection to the server.

Class
TCustomDAConnection

Syntax
procedure Connect; overload;procedure Connect(const
ConnectString: string); overload;

Remarks
Call the Connect method to establish a connection to the server. Connect sets the Connected
property to True. If LoginPrompt is True, Connect prompts user for login information as
required by the server, or otherwise tries to establish a connection using values provided in
the Username, Password, and Server properties.
© 2019 Devart

308

SQL Server Data Access Components

Note, if you would like to use SDAC in service, console or just at a separate thread, you needto call CoInitialize for each thread. Also remember to call CoUnInitialize at the end of a thread.

See Also
Disconnect
Username
Password
ServerConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.4 CreateSQL Method

Creates a component for queries execution.

Class
TCustomDAConnection

Syntaxfunction CreateSQL: TCustomDASQL; virtual;
Return ValueA new instance of the class.

Remarks
Call the CreateSQL to return a new instance of the TCustomDASQL class and associates itwith this connection object. In the descendant classes this method should be overridden to
create an appropriate descendant of the TCustomDASQL component.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.5 Disconnect Method

Performs disconnect.

Class
TCustomDAConnection© 2019 DevartReference

309

Syntax
procedure Disconnect;

Remarks
Call the Disconnect method to drop a connection to database. Before the connection
component is deactivated, all associated datasets are closed. Calling Disconnect is similar tosetting the Connected property to False.
In most cases, closing a connection frees system resources allocated to the connection.
If user transaction is active, e.g. the InTransaction flag is set, calling to Disconnect rolls backthe current user transaction.
Note: If a previously active connection is closed and then reopened, any associated datasets
must be individually reopened; reopening the connection does not automatically reopen
associated datasets.

See Also
Connect© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.6 ExecProc Method

Allows to execute stored procedure or function providing its name and parameters.

Class
TCustomDAConnection

Syntaxfunction ExecProc(const Name: string; const Params: array ofvariant): variant; virtual;Parameters
Name
Holds the name of the stored procedure or function.
ParamsHolds the parameters of the stored procedure or function.
Return Value
the result of the stored procedure.

© 2019 Devart

310

SQL Server Data Access Components

Remarks
Allows to execute stored procedure or function providing its name and parameters.
Use the following Name value syntax for executing specific overloaded routine:"StoredProcName:1" or "StoredProcName:5". The first example executes the first overloaded
stored procedure, while the second example executes the fifth overloaded procedure.
Assign parameters' values to the Params array in exactly the same order and number as they
appear in the stored procedure declaration. Out parameters of the procedure can beaccessed with the ParamByName procedure.
If the value of an input parameter was not included to the Params array, parameter default
value is taken. Only parameters at the end of the list can be unincluded to the Params array. If
the parameter has no default value, the NULL value is sent.
Note: Stored functions unlike stored procedures return result values that are obtainedinternally through the RESULT parameter. You will no longer have to provide anonymous
value in the Params array to describe the result of the function. The stored function result isobtained from the Params[0] indexed property or with the ParamByName('RESULT') methodcall.
For further examples of parameter usage see ExecSQL, ExecSQLEx.

ExampleFor example, having stored function declaration presented in Example 1), you may execute it
and retrieve its result with commands presented in Example 2):
Example 1)
CREATE procedure MY_SUM (A INTEGER,B INTEGER)
RETURNS (RESULT INTEGER)
asbegin
Result = a + b;
end;
Example 2)
Label1.Caption:= MyMSConnection1.ExecProc('My_Sum', [10, 20]);
Label2.Caption:= MyMSConnection1.ParamByName('Result').AsString;See Also
ExecProcEx
ExecSQLExecSQLEx© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

311

Reserved.
5.10.1.4.3.7 ExecProcEx Method

Allows to execute a stored procedure or function.

Class
TCustomDAConnection

Syntaxfunction ExecProcEx(const Name: string; const Params: array ofvariant): variant; virtual;Parameters
Name
Holds the stored procedure name.
ParamsHolds an array of pairs of parameters' names and values.
Return Value
the result of the stored procedure.

Remarks
Allows to execute a stored procedure or function. Provide the stored procedure name and its
parameters to the call of ExecProcEx.
Use the following Name value syntax for executing specific overloaded routine:"StoredProcName:1" or "StoredProcName:5". The first example executes the first overloaded
stored procedure, while the second example executes the fifth overloaded procedure.
Assign pairs of parameters' names and values to a Params array so that every name comes
before its corresponding value when an array is being indexed.
Out parameters of the procedure can be accessed with the ParamByName procedure. If thevalue for an input parameter was not included to the Params array, the parameter default
value is taken. If the parameter has no default value, the NULL value is sent.
Note: Stored functions unlike stored procedures return result values that are obtainedinternally through the RESULT parameter. You will no longer have to provide anonymous
value in the Params array to describe the result of the function. Stored function result isobtained from the Params[0] indexed property or with the ParamByName('RESULT') methodcall.
For an example of parameters usage see ExecSQLEx.

Example© 2019 Devart

312

SQL Server Data Access Components

If you have some stored procedure accepting four parameters, and you want to provide
values only for the first and fourth parameters, you should call ExecProcEx in the following
way:

Connection.ExecProcEx('Some_Stored_Procedure', ['Param_Name1', 'Param_Value1

See Also
ExecSQLExecSQLEx
ExecProc© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.8 ExecSQL Method

Executes a SQL statement with parameters.

Class
TCustomDAConnection

Syntaxfunction ExecSQL(const Text: string): variant;overload;function ExecSQL(const Text: string; const Params:array of variant): variant; overload; virtual;Parameters
Text
a SQL statement to be executed.
ParamsArray of parameter values arranged in the same order as they appear in SQL statement.
Return Value
Out parameter with the name Result will hold the result of function having data type dtString.
Otherwise returns Null.

Remarks
Use the ExecSQL method to execute any SQL statement outside the TCustomDADataSet or
TCustomDASQL components. Supply the Params array with the values of parametersarranged in the same order as they appear in a SQL statement which itself is passed to the
Text string parameter.

© 2019 DevartReference

313

See Also
ExecSQLEx
ExecProc© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.9 ExecSQLEx Method

Executes any SQL statement outside the TQuery or TSQL components.

Class
TCustomDAConnection

Syntaxfunction ExecSQLEx(const Text: string; const Params: array ofvariant): variant; virtual;Parameters
Text
a SQL statement to be executed.
ParamsArray of parameter values arranged in the same order as they appear in SQL statement.
Return Value
Out parameter with the name Result will hold the result of a function having data typedtString. Otherwise returns Null.

Remarks
Call the ExecSQLEx method to execute any SQL statement outside the TQuery or TSQL
components. Supply the Params array with values arranged in pairs of parameter name andits value. This way each parameter name in the array is found on even index values whereas
parameter value is on odd index value but right after its parameter name. The parameter pairs
must be arranged according to their occurrence in a SQL statement which itself is passed in
the Text string parameter.
The Params array must contain all IN and OUT parameters defined in the SQL statement.
For OUT parameters provide any values of valid types so that they are explicitly defined
before call to the ExecSQLEx method.
Out parameter with the name Result will hold the result of a function having data type dtString.
If neither of the parameters in the Text statement is named Result, ExecSQLEx will return© 2019 Devart

314

SQL Server Data Access Components

Null.
To get the values of OUT parameters use the ParamByName function.

ExampleMSConnection.ExecSQLEx('begin :A:= :B + :C; end;',['A', 0, 'B', 5, 'C', 3]);
A:= MSConnection.ParamByName('A').AsInteger;

See Also
ExecSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.10 GetDatabaseNames Method

Returns a database list from the server.

Class
TCustomDAConnection

Syntax
procedure GetDatabaseNames(List: TStrings); virtual;Parameters
List
A TStrings descendant that will be filled with database names.

Remarks
Populates a string list with the names of databases.
Note: Any contents already in the target string list object are eliminated and overwritten bydata produced by GetDatabaseNames.

See Also
GetTableNames
GetStoredProcNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference315

5.10.1.4.3.11 GetKeyFieldNames Method

Provides a list of available key field names.

Class
TCustomDAConnection

Syntax
procedure GetKeyFieldNames(const TableName: string; List:
TStrings); virtual;Parameters
TableName
Holds the table nameList
The list of available key field names
Return Value
Key field name

Remarks
Call the GetKeyFieldNames method to get the names of available key fields. Populates astring list with the names of key fields in tables.

See Also
GetTableNames
GetStoredProcNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.12 GetStoredProcNames Method

Returns a list of stored procedures from the server.

Class
TCustomDAConnection

Syntax
procedure GetStoredProcNames(List: TStrings; AllProcs: boolean =False); virtual;© 2019 Devart

316

SQL Server Data Access Components

Parameters
List
A TStrings descendant that will be filled with the names of stored procedures in the
database.
AllProcs
True, if stored procedures from all schemas or including system procudures (depending on
the server) are returned. False otherwise.

Remarks
Call the GetStoredProcNames method to get the names of available stored procedures andfunctions. GetStoredProcNames populates a string list with the names of stored procs in the
database. If AllProcs = True, the procedure returns to the List parameter the names of thestored procedures that belong to all schemas; otherwise, List will contain the names offunctions that belong to the current schema.
Note: Any contents already in the target string list object are eliminated and overwritten bydata produced by GetStoredProcNames.

See Also
GetDatabaseNames
GetTableNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.13 GetTableNames Method

Provides a list of available tables names.

Class
TCustomDAConnection

Syntax
procedure GetTableNames(List: TStrings; AllTables: boolean =False; OnlyTables: boolean = False); virtual;Parameters
List
A TStrings descendant that will be filled with table names.
AllTables
True, if procedure returns all table names including the names of system tables to the List
parameter.
© 2019 DevartReference

317

OnlyTables

Remarks
Call the GetTableNames method to get the names of available tables. Populates a string list
with the names of tables in the database. If AllTables = True, procedure returns all tablenames including the names of system tables to the List parameter, otherwise List will notcontain the names of system tables. If AllTables = True, the procedure returns to the List
parameter the names of the tables that belong to all schemas; otherwise, List will contain thenames of the tables that belong to the current schema.
Note: Any contents already in the target string list object are eliminated and overwritten by thedata produced by GetTableNames.

See Also
GetDatabaseNames
GetStoredProcNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.14 MonitorMessage Method

Sends a specified message through the TCustomDASQLMonitor component.

Class
TCustomDAConnection

Syntax
procedure MonitorMessage(const Msg: string);
Parameters
Msg
Message text that will be sent.

Remarks
Call the MonitorMessage method to output specified message via theTCustomDASQLMonitor component.

See Also
TCustomDASQLMonitor© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

318

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.10.1.4.3.15 Ping Method

Used to check state of connection to the server.

Class
TCustomDAConnection

Syntax
procedure Ping;

Remarks
The method is used for checking server connection state.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.16 RemoveFromPool Method

Marks the connection that should not be returned to the pool after disconnect.

Class
TCustomDAConnection

Syntax
procedure RemoveFromPool;

Remarks
Call the RemoveFromPool method to mark the connection that should be deleted after
disconnect instead of returning to the connection pool.

See Also
Pooling
PoolingOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference319

5.10.1.4.3.17 Rollback Method

Discards all current data changes and ends transaction.

Class
TCustomDAConnection

Syntax
procedure Rollback; virtual;

Remarks
Call the Rollback method to discard all updates, insertions, and deletions of data associatedwith the current transaction to the database server and then end the transaction. The current
transaction is the last transaction started by calling StartTransaction.

See Also
CommitStartTransaction
TCustomMSDataSet.FetchAll© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.3.18 StartTransaction Method

Begins a new user transaction.

Class
TCustomDAConnection

Syntax
procedure StartTransaction; virtual;

Remarks
Call the StartTransaction method to begin a new user transaction against the databaseserver. Before calling StartTransaction, an application should check the status of the
InTransaction property. If InTransaction is True, indicating that a transaction is already inprogress, a subsequent call to StartTransaction without first calling Commit or Rollback to
end the current transaction raises EDatabaseError. Calling StartTransaction when

© 2019 Devart

320

SQL Server Data Access Components

connection is closed also raises EDatabaseError.
Updates, insertions, and deletions that take place after a call to StartTransaction are held by
the server until an application calls Commit to save the changes, or Rollback to cancel them.
In SQL Server real transaction begins only on the first execute of data modification SQL
statement.
Note: In some cases TCustomMSDataSet.FetchAll may conflict with transaction control(EOLEDBError 'Cannot create new connection because in manual or distributed transaction
mode.') or may cause deadlocking on Post on editing queries with ORDER BY clause.
Also no transactions can be started and there are underfetched datasets within theconnection.

See Also
CommitRollback
InTransaction
TCustomMSConnection.IsolationLevel© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.4 Events

Events of the TCustomDAConnection class.
For a complete list of the TCustomDAConnection class members, see theTCustomDAConnection Members topic.

PublicName

Description
This event occurs whenconnection was lost.
This event occurs when anerror has arisen in theconnection.

OnConnectionLost
OnErrorSee Also
TCustomDAConnection Class
TCustomDAConnection Class Members© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

321

Reserved.
5.10.1.4.4.1 OnConnectionLost Event

This event occurs when connection was lost.

Class
TCustomDAConnection

Syntaxproperty OnConnectionLost: TConnectionLostEvent;Remarks
Write the OnConnectionLost event handler to process fatal errors and perform failover.
Note: To use the OnConnectionLost event handler, you should explicitly add the MemData
unit to the 'uses' list and set the TCustomDAConnection.Options.LocalFailover property to
True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.4.4.2 OnError Event

This event occurs when an error has arisen in the connection.

Class
TCustomDAConnection

Syntaxproperty OnError: TDAConnectionErrorEvent;Remarks
Write the OnError event handler to respond to errors that arise with connection. Check the Eparameter to get the error code. Set the Fail parameter to False to prevent an error dialog
from being displayed and to raise the EAbort exception to cancel current operation. The
default value of Fail is True.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

322

SQL Server Data Access Components

5.10.1.5 TCustomDADataSet Class

Encapsulates general set of properties, events, and methods for working with data accessed
through various database engines.
For a list of all members of this type, see TCustomDADataSet members.

Unit
DBAccess

SyntaxTCustomDADataSet = class(TMemDataSet);

Remarks
TCustomDADataSet encapsulates general set of properties, events, and methods for working
with data accessed through various database engines. All database-specific features aresupported by descendants of TCustomDADataSet.
Applications should not use TCustomDADataSet objects directly.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.1 Members

TCustomDADataSet class overview.

Properties
Name
BaseSQL

CachedUpdates (inherited from TMemDataSet)
Conditions

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.
Used to add WHERE
conditions to a query© 2019 DevartReference

Connection
DataTypeMap

Debug

DetailFields

Disconnected

FetchRows

FilterSQL

FinalSQL

IndexFieldNames (inherited from TMemDataSet)
IsQuery
KeyExclusive (inherited from TMemDataSet)

KeyFields© 2019 Devart

323

Used to specify aconnection object to use toconnect to a data store.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.

324

SQL Server Data Access Components

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount
MacrosMasterFields

MasterSource

Options

ParamCheck

ParamCount

Params
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly

Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour ofTCustomDADataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Used to view and set
parameter names, values,
and data types dynamically.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users from© 2019 DevartReference

RefreshOptions

RowsAffected

SQL

SQLDelete

SQLInsert

SQLLock

SQLRecCountSQLRefresh

SQLUpdate

UniDirectional

UpdateRecordTypes (inherited from TMemDataSet)© 2019 Devart

325

updating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to indicate the update
status for the current record
when cached updates areenabled.

326

SQL Server Data Access Components

UpdatesPending (inherited from TMemDataSet)

Used to check the status of
the cached updates buffer.

Methods
Name
AddWhere
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)
BreakExec
CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)

CreateBlobStream

DeferredPost (inherited from TMemDataSet)

DeleteWhere

EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

Description
Adds condition to the
WHERE clause of SELECT
statement in the SQL
property.
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Breaks execution of a SQL
statement on the server.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Used to obtain a stream forreading data from or writing
data to a BLOB field,
specified by the Field
parameter.
Makes permanent changes
to the database server.
Removes WHERE clausefrom the SQL property andassigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.

© 2019 DevartReference

ExecuteExecuting

FetchedFetching

FetchingAll

FindKey
FindMacro

FindNearest

FindParam

GetBlob (inherited from TMemDataSet)

GetDataType
GetFieldObject
GetFieldPrecision
GetFieldScale
GetKeyFieldNames© 2019 Devart

327

Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Determines if a parameterwith the specified nameexists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Returns internal field types
defined in the MemData andaccompanying modules.
Returns a multireference
shared object from field.
Retrieves the precision of anumber field.
Retrieves the scale of anumber field.
Provides a list of available

328

SQL Server Data Access Components

GetOrderBy

GotoCurrent

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock
MacroByName

ParamByName

PrepareRefreshRecord
RestoreSQL
RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL

SaveToXML (inherited from TMemDataSet)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Locks the current record.
Finds a Macro with thename passed in Name.
Sets or uses parameter
information for a specificparameter based on its
name.
Allocates, opens, andparses cursor for a query.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO© 2019 DevartReference

SetOrderBy
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved
UnLock
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

329

format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
AfterExecute
AfterFetch
AfterUpdateExecute© 2019 Devart

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing

330

SQL Server Data Access Components

BeforeFetch

BeforeUpdateExecute

OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

insert, delete, update, lockand refresh operations.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lock,and refresh operations.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.10.1.5.2 Properties

Properties of the TCustomDADataSet class.
For a complete list of the TCustomDADataSet class members, see the TCustomDADataSet
Members topic.

PublicName
BaseSQL

CachedUpdates (inherited from TMemDataSet)
Conditions
Connection
DataTypeMap
Debug

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.
Used to add WHERE
conditions to a query
Used to specify aconnection object to use toconnect to a data store.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'© 2019 DevartReference

DetailFields

Disconnected

FetchRows

FilterSQL

FinalSQL

IndexFieldNames (inherited from TMemDataSet)
IsQuery
KeyExclusive (inherited from TMemDataSet)

KeyFields

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)© 2019 Devart

331

values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.

332

SQL Server Data Access Components

MacroCount
MacrosMasterFields

MasterSource

Options

ParamCheck

ParamCount

Params
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly
RefreshOptions

RowsAffected

Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour ofTCustomDADataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Used to view and set
parameter names, values,
and data types dynamically.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.

© 2019 DevartReference

SQL

SQLDelete

SQLInsert

SQLLock

SQLRecCountSQLRefresh

SQLUpdate

UniDirectional

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

See Also
TCustomDADataSet Class
TCustomDADataSet Class Members© 2019 Devart

333

Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

334

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.1 BaseSQL Property

Used to return SQL text without any changes performed by AddWhere, SetOrderBy, andFilterSQL.

Class
TCustomDADataSet

Syntaxproperty BaseSQL: string;

Remarks
Use the BaseSQL property to return SQL text without any changes performed by AddWhere,
SetOrderBy, and FilterSQL, only macros are expanded. SQL text with all these changes canbe returned by FinalSQL.

See Also
FinalSQL
AddWhere
SaveSQLSQLSaved
RestoreSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.2 Conditions Property

Used to add WHERE conditions to a queryClass
TCustomDADataSet

Syntaxproperty Conditions: TDAConditions stored False;© 2019 DevartReference

335

See Also
TDAConditions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.3 Connection Property

Used to specify a connection object to use to connect to a data store.

Class
TCustomDADataSet

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomDAConnection or its
descendant class objects.
At runtime, link an instance of a TCustomDAConnection descendant to the Connection
property.

See Also
TCustomMSConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.4 DataTypeMap Property

Used to set data type mapping rules

Class
TCustomDADataSet

Syntaxproperty DataTypeMap: TDAMapRules stored IsMapRulesStored;© 2019 Devart

336

SQL Server Data Access Components

See Also
TDAMapRules© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.5 Debug Property

Used to display executing statement, all its parameters' values, and the type of parameters.

Class
TCustomDADataSet

Syntaxproperty Debug: boolean default False;

Remarks
Set the Debug property to True to display executing statement and all its parameters' values.
Also displays the type of parameters.
You should add the SdacVcl unit to the uses clause of any unit in your project to make the
Debug property work.
Note: If TMSSQLMonitor is used in the project and the TMSSQLMonitor.Active property is set
to False, the debug window is not displayed.

See Also
TCustomDASQL.Debug© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.6 DetailFields Property

Used to specify the fields that correspond to the foreign key fields from MasterFields whenbuilding master/detail relationship.

Class
TCustomDADataSet

Syntaxproperty DetailFields: string;© 2019 DevartReference

337

Remarks
Use the DetailFields property to specify the fields that correspond to the foreign key fields
from MasterFields when building master/detail relationship. DetailFields is a string containing
one or more field names in the detail table. Separate field names with semicolons.
Use Field Link Designer to set the value in design time.

See Also
MasterFields
MasterSource© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.7 Disconnected Property

Used to keep dataset opened after connection is closed.

Class
TCustomDADataSet

Syntaxproperty Disconnected: boolean;

Remarks
Set the Disconnected property to True to keep dataset opened after connection is closed.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.8 FetchRow s Property

Used to define the number of rows to be transferred across the network at the same time.

Class
TCustomDADataSet

Syntaxproperty FetchRows: integer default 25;

Remarks© 2019 Devart

338

SQL Server Data Access Components

The number of rows that will be transferred across the network at the same time. This
property can have a great impact on performance. So it is preferable to choose the optimalvalue of the FetchRows property for each SQL statement and software/hardware
configuration experimentally.
The default value is 25.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.9 FilterSQL Property

Used to change the WHERE clause of SELECT statement and reopen a query.

Class
TCustomDADataSet

Syntaxproperty FilterSQL: string;

Remarks
The FilterSQL property is similar to the Filter property, but it changes the WHERE clause of
SELECT statement and reopens query. Syntax is the same to the WHERE clause.
Note: the FilterSQL property adds a value to the WHERE condition as is. If you expect thisvalue to be enclosed in brackets, you should bracket it explicitly.

ExampleQuery1.FilterSQL := 'Dept >= 20 and DName LIKE ''M%''';

See Also
AddWhere© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.10 FinalSQL Property

Used to return SQL text with all changes performed by AddWhere, SetOrderBy, andFilterSQL, and with expanded macros.

Class© 2019 DevartReference

339

TCustomDADataSet

Syntaxproperty FinalSQL: string;

Remarks
Use FinalSQL to return SQL text with all changes performed by AddWhere, SetOrderBy, andFilterSQL, and with expanded macros. This is the exact statement that will be passed on to
the database server.

See Also
FinalSQL
AddWhere
SaveSQLSQLSaved
RestoreSQLBaseSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.11 IsQuery Property

Used to check whether SQL statement returns rows.

Class
TCustomDADataSet

Syntaxproperty IsQuery: boolean;

Remarks
After the TCustomDADataSet component is prepared, the IsQuery property returns True if
SQL statement is a SELECT query.
Use the IsQuery property to check whether the SQL statement returns rows or not.
IsQuery is a read-only property. Reading IsQuery on unprepared dataset raises an exception.

© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

340

SQL Server Data Access Components

5.10.1.5.2.12 KeyFields Property

Used to build SQL statements for the SQLDelete, SQLInsert, and SQLUpdate properties ifthey were empty before updating the database.

Class
TCustomDADataSet

Syntaxproperty KeyFields: string;

Remarks
TCustomDADataset uses the KeyFields property to build SQL statements for the SQLDelete,
SQLInsert, and SQLUpdate properties if they were empty before updating the database. For
this feature KeyFields may hold a list of semicolon-delimited field names. If KeyFields is notdefined before opening a dataset, TCustomDADataset uses the metainformation sent by theserver together with data.

See Also
SQLDelete
SQLInsert
SQLRefresh
SQLUpdate© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.13 MacroCount Property

Used to get the number of macros associated with the Macros property.

Class
TCustomDADataSet

Syntaxproperty MacroCount: word;

Remarks
Use the MacroCount property to get the number of macros associated with the Macros© 2019 DevartReference341

property.

See Also
Macros© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.14 Macros Property

Makes it possible to change SQL queries easily.

Class
TCustomDADataSet

Syntaxproperty Macros: TMacros stored False;

Remarks
With the help of macros you can easily change SQL query text at design- or runtime. Marcos
extend abilities of parameters and allow to change conditions in a WHERE clause or sortorder in an ORDER BY clause. You just insert &MacroName in the SQL query text andchange value of macro in the Macro property editor at design time or call the MacroByName
function at run time. At the time of opening the query macro is replaced by its value.

ExampleMSQuery.SQL:= 'SELECT * FROM Dept ORDER BY &Order';MSQuery.MacroByName('Order').Value:= 'DeptNo';
MSQuery.Open;

See Also
TMacroMacroByName
Params© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

342

SQL Server Data Access Components

5.10.1.5.2.15 MasterFields Property

Used to specify the names of one or more fields that are used as foreign keys for dataset
when establishing detail/master relationship between it and the dataset specified in
MasterSource.

Class
TCustomDADataSet

Syntaxproperty MasterFields: string;

Remarks
Use the MasterFields property after setting the MasterSource property to specify the names of
one or more fields that are used as foreign keys for this dataset when establishing detail/master relationship between it and the dataset specified in MasterSource.
MasterFields is a string containing one or more field names in the master table. Separate fieldnames with semicolons.
Each time the current record in the master table changes, the new values in these fields areused to select corresponding records in this table for display.
Use Field Link Designer to set the values at design time after setting the MasterSource
property.

See Also
DetailFields
MasterSource
Master/Detail Relationships© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.16 MasterSource Property

Used to specify the data source component which binds current dataset to the master one.

Class
TCustomDADataSet

Syntaxproperty MasterSource: TDataSource;© 2019 DevartReference

343

Remarks
The MasterSource property specifies the data source component which binds current dataset
to the master one.
TCustomDADataset uses MasterSource to extract foreign key fields values from the masterdataset when building master/detail relationship between two datasets. MasterSource must
point to another dataset; it cannot point to this dataset component.
When MasterSource is not nil dataset fills parameter values with corresponding field values
from the current record of the master dataset.
Note: Do not set the DataSource property when building master/detail relationships. Although
it points to the same object as the MasterSource property, it may lead to undesirable results.

See Also
MasterFields
DetailFields
Master/Detail Relationships© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.17 Options Property

Used to specify the behaviour of TCustomDADataSet object.

Class
TCustomDADataSet

Syntaxproperty Options: TDADataSetOptions;Remarks
Set the properties of Options to specify the behaviour of a TCustomDADataSet object.
Descriptions of all options are in the table below.

Option Name
AutoPrepare
CacheCalcFields© 2019 Devart

Description
Used to execute automatic Prepare on thequery execution.
Used to enable caching of the
TField.Calculated and TField.Lookup
fields.

344

SQL Server Data Access Components

CompressBlobMode
DefaultValues

DetailDelay

FieldsOrigin
FlatBuffers
InsertAllSetFields

LocalMasterDetail

LongStrings

MasterFieldsNullable

NumberRange

QueryRecCount

QuoteNames
RemoveOnRefresh
RequiredFields
ReturnParams

Used to store values of the BLOB fields incompressed form.
Used to request default values/expressions
from the server and assign them to theDefaultExpression property.
Used to get or set a delay in milliseconds
before refreshing detail dataset whilenavigating master dataset.
Used for TCustomDADataSet to fill theOrigin property of the TField objects byappropriate value when opening a dataset.
Used to control how a dataset treats dataof the ftString and ftVarBytes fields.
Used to include all set dataset fields in thegenerated INSERT statement
Used for TCustomDADataSet to use local
filtering to establish master/detail
relationship for detail dataset and does notrefer to the server.
Used to represent string fields with thelength that is greater than 255 as
TStringField.
Allows to use NULL values in the fields bywhich the relation is built, when generating
the query for the Detail tables (when thisoption is enabled, the performance can getworse).
Used to set the MaxValue and MinValue
properties of TIntegerField and TFloatField
to appropriate values.
Used for TCustomDADataSet to perform
additional query to get the record count forthis SELECT, so the RecordCount property
reflects the actual number of records.
Used for TCustomDADataSet to quote all
database object names in autogenerated
SQL statements such as update SQL.
Used for a dataset to locally remove a
record that can not be found on the server.
Used for TCustomDADataSet to set theRequired property of the TField objects for
the NOT NULL fields.
Used to return the new value of fields todataset after insert or update.
© 2019 DevartReference

345

Used for a dataset to set the ReadOnly
property to True for all fields that do notbelong to UpdatingTable or can not be
updated.
Used for TCustomDADataSet to raise an
exception when the number of updated ordeleted records is not equal 1.
Specifies whether to discard all trailingspaces in the string fields of a dataset.
Used to include all dataset fields in thegenerated UPDATE and INSERT
statements.
Used to get or set a value that enables ordisables batch processing support, andspecifies the number of commands thatcan be executed in a batch.

SetFieldsReadOnly

StrictUpdate
TrimFixedChar
UpdateAllFields

UpdateBatchSize

See Also
Master/Detail Relationships
TMemDataSet.CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.18 ParamCheck Property

Used to specify whether parameters for the Params property are generated automaticallyafter the SQL property was changed.

Class
TCustomDADataSet

Syntaxproperty ParamCheck: boolean default True;

Remarks
Use the ParamCheck property to specify whether parameters for the Params property are
generated automatically after the SQL property was changed.
Set ParamCheck to True to let dataset automatically generate the Params property for thedataset based on a SQL statement.
Setting ParamCheck to False can be used if the dataset component passes to a server the© 2019 Devart

346

SQL Server Data Access Components

DDL statements that contain, for example, declarations of stored procedures whichthemselves will accept parameterized values. The default value is True.

See Also
Params© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.19 ParamCount Property

Used to indicate how many parameters are there in the Params property.

Class
TCustomDADataSet

Syntaxproperty ParamCount: word;

Remarks
Use the ParamCount property to determine how many parameters are there in the Params
property.

See Also
Params© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.20 Params Property

Used to view and set parameter names, values, and data types dynamically.

Class
TCustomDADataSet

Syntaxproperty Params: TDAParams stored False;

Remarks
Contains the parameters for a query's SQL statement.
© 2019 DevartReference

347

Access Params at runtime to view and set parameter names, values, and data types
dynamically (at design time use the Parameters editor to set the parameter information).
Params is a zero-based array of parameter records. Index specifies the array element toaccess.
An easier way to set and retrieve parameter values when the name of each parameter isknown is to call ParamByName.

See Also
ParamByName
Macros© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.21 ReadOnly Property

Used to prevent users from updating, inserting, or deleting data in the dataset.

Class
TCustomDADataSet

Syntaxproperty ReadOnly: boolean default False;

Remarks
Use the ReadOnly property to prevent users from updating, inserting, or deleting data in thedataset. By default, ReadOnly is False, meaning that users can potentially alter data stored in
the dataset.
To guarantee that users cannot modify or add data to a dataset, set ReadOnly to True.
When ReadOnly is True, the dataset's CanModify property is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.5.2.22 RefreshOptions Property

Used to indicate when the editing record is refreshed.

Class
TCustomDADataSet© 2019 Devart

Provide Feedback

348

SQL Server Data Access Components

Syntaxproperty RefreshOptions: TRefreshOptions default [];Remarks
Use the RefreshOptions property to determine when the editing record is refreshed.
Refresh is performed by the RefreshRecord method.
It queries the current record and replaces one in the dataset. Refresh record is useful when
the table has triggers or the table fields have default values. Use roBeforeEdit to get actual
data before editing.
The default value is [].

See Also
RefreshRecord© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.23 Row sAffected Property

Used to indicate the number of rows which were inserted, updated, or deleted during the lastquery operation.

Class
TCustomDADataSet

Syntaxproperty RowsAffected: integer;

Remarks
Check RowsAffected to determine how many rows were inserted, updated, or deleted during
the last query operation. If RowsAffected is -1, the query has not inserted, updated, or deleted
any rows.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.24 SQL Property

Used to provide a SQL statement that a query component executes when its Open method iscalled.
© 2019 DevartReference

349

Class
TCustomDADataSet

Syntaxproperty SQL: TStrings;

Remarks
Use the SQL property to provide a SQL statement that a query component executes when its
Open method is called. At the design time the SQL property can be edited by invoking theString List editor in Object Inspector.
When SQL is changed, TCustomDADataSet calls Close and UnPrepare.

See Also
SQLInsert
SQLUpdate
SQLDelete
SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.25 SQLDelete Property

Used to specify a SQL statement that will be used when applying a deletion to a record.

Class
TCustomDADataSet

Syntaxproperty SQLDelete: TStrings;

Remarks
Use the SQLDelete property to specify the SQL statement that will be used when applying adeletion to a record. Statements can be parameterized queries.
To create a SQLDelete statement at design-time, use the query statements editor.

Example
DELETE FROM Orders© 2019 Devart

350

SQL Server Data Access Components

WHERE
OrderID = :Old_OrderID

See Also
SQL
SQLInsert
SQLUpdate
SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.26 SQLInsert Property

Used to specify the SQL statement that will be used when applying an insertion to a dataset.

Class
TCustomDADataSet

Syntaxproperty SQLInsert: TStrings;

Remarks
Use the SQLInsert property to specify the SQL statement that will be used when applying an
insertion to a dataset. Statements can be parameterized queries. Names of the parameters
should be the same as field names. Parameters prefixed with OLD_ allow using current
values of fields prior to the actual operation.
Use ReturnParam to return OUT parameters back to dataset.
To create a SQLInsert statement at design-time, use the query statements editor.
If you specify SQLInsert not depending on TCustomMSDataSet.Options.QueryIdentity, thevalue of the Identity filed won't be returned on execution Insert(Append).Post. To avoid the
problem, you should add the following the code in the end of SQLInsert:
INSERT INTO Orders(Shipname)
VALUES(:Shipname)See Also
SQL
SQLUpdate
SQLDelete© 2019 DevartReference

351

SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.27 SQLLock Property

Used to specify a SQL statement that will be used to perform a record lock.

Class
TCustomDADataSet

Syntaxproperty SQLLock: TStrings;

Remarks
Use the SQLLock property to specify a SQL statement that will be used to perform a record
lock. Statements can be parameterized queries. Names of the parameters should be thesame as field names. The parameters prefixed with OLD_ allow to use current values offields prior to the actual operation.
To create a SQLLock statement at design-time, the use query statement editor.

See Also
SQL
SQLInsert
SQLUpdate
SQLDelete
SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.28 SQLRecCount Property

Used to specify the SQL statement that is used to get the record count when opening adataset.

Class
TCustomDADataSet

Syntax© 2019 Devart

352

SQL Server Data Access Components

property SQLRecCount: TStrings;

Remarks
Use the SQLRecCount property to specify the SQL statement that is used to get the record
count when opening a dataset. The SQL statement is used if the
TDADataSetOptions.QueryRecCount property is True, and the TCustomDADataSet.FetchAll
property is False. Is not used if the FetchAll property is True.
To create a SQLRecCount statement at design-time, use the query statements editor.

See Also
SQLInsert
SQLUpdate
SQLDelete
SQLRefresh
TDADataSetOptions
M:Devart.Dac.TCustomDADataSet.FetchingAll© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.29 SQLRefresh Property

Used to specify a SQL statement that will be used to refresh current record by calling theRefreshRecord procedure.

Class
TCustomDADataSet

Syntaxproperty SQLRefresh: TStrings;

Remarks
Use the SQLRefresh property to specify a SQL statement that will be used to refresh current
record by calling the RefreshRecord procedure.
Different behavior is observed when the SQLRefresh property is assigned with a single
WHERE clause that holds frequently altered search condition. In this case the WHERE
clause from SQLRefresh is combined with the same clause of the SELECT statement in a
SQL property and this final query is then sent to the database server.

© 2019 DevartReference353

To create a SQLRefresh statement at design-time, use the query statements editor.

ExampleSELECT Shipname FROM Orders
WHERE
OrderID = :OrderID

See Also
RefreshRecord
SQL
SQLInsert
SQLUpdate
SQLDelete© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.30 SQLUpdate Property

Used to specify a SQL statement that will be used when applying an update to a dataset.

Class
TCustomDADataSet

Syntaxproperty SQLUpdate: TStrings;

Remarks
Use the SQLUpdate property to specify a SQL statement that will be used when applying an
update to a dataset. Statements can be parameterized queries. Names of the parameters
should be the same as field names. The parameters prefixed with OLD_ allow to use current
values of fields prior to the actual operation.
Use ReturnParam to return OUT parameters back to the dataset.
To create a SQLUpdate statement at design-time, use the query statement editor.

ExampleUPDATE Orders
set
ShipName = :ShipName
WHERE
OrderID = :Old_OrderID© 2019 Devart

354

SQL Server Data Access Components

See Also
SQL
SQLInsert
SQLDelete
SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.2.31 UniDirectional Property

Used if an application does not need bidirectional access to records in the result set.

Class
TCustomDADataSet

Syntaxproperty UniDirectional: boolean default False;

Remarks
Traditionally SQL cursors are unidirectional. They can travel only forward through a dataset.
TCustomDADataset, however, permits bidirectional travelling by caching records. If an
application does not need bidirectional access to the records in the result set, set
UniDirectional to True. When UniDirectional is True, an application requires less memory andperformance is improved. However, UniDirectional datasets cannot be modified. In
FetchAll=False mode data is fetched on demand. When UniDirectional is set to True, data is
fetched on demand as well, but obtained rows are not cached except for the current row. In
case if the Unidirectional property is True, the FetchAll property will be automatically set to
False. And if the FetchAll property is True, the Unidirectional property will be automatically set
to False. The default value of UniDirectional is False, enabling forward and backward
navigation.
Note: Pay attention to the specificity of using the FetchAll property=False

See Also
TMSQuery.FetchAll© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference355

5.10.1.5.3 Methods

Methods of the TCustomDADataSet class.
For a complete list of the TCustomDADataSet class members, see the TCustomDADataSet
Members topic.

PublicName
AddWhere
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)
BreakExec
CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)

CreateBlobStream

DeferredPost (inherited from TMemDataSet)

DeleteWhere

EditRangeEnd (inherited from TMemDataSet)
EditRangeStart (inherited from TMemDataSet)© 2019 Devart

Description
Adds condition to the
WHERE clause of SELECT
statement in the SQL
property.
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Breaks execution of a SQL
statement on the server.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Used to obtain a stream forreading data from or writing
data to a BLOB field,
specified by the Field
parameter.
Makes permanent changes
to the database server.
Removes WHERE clausefrom the SQL property andassigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing

356

SQL Server Data Access Components

ExecuteExecuting

FetchedFetching

FetchingAll

FindKey
FindMacro

FindNearest

FindParam

GetBlob (inherited from TMemDataSet)

GetDataType
GetFieldObject
GetFieldPrecision
GetFieldScale

range.
Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Determines if a parameterwith the specified nameexists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Returns internal field types
defined in the MemData andaccompanying modules.
Returns a multireference
shared object from field.
Retrieves the precision of anumber field.
Retrieves the scale of anumber field.
© 2019 DevartReference

GetKeyFieldNames
GetOrderBy

GotoCurrent

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock
MacroByName

ParamByName

PrepareRefreshRecord
RestoreSQL
RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL
SaveToXML (inherited from TMemDataSet)© 2019 Devart

357

Provides a list of available
key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Locks the current record.
Finds a Macro with thename passed in Name.
Sets or uses parameter
information for a specificparameter based on its
name.
Allocates, opens, andparses cursor for a query.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML

358

SQL Server Data Access Components

SetOrderBy
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved
UnLock
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TCustomDADataSet Class
TCustomDADataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference359

5.10.1.5.3.1 AddWhere Method

Adds condition to the WHERE clause of SELECT statement in the SQL property.

Class
TCustomDADataSet

Syntax
procedure AddWhere(const Condition: string);
Parameters
Condition
Holds the condition that will be added to the WHERE clause.

Remarks
Call the AddWhere method to add a condition to the WHERE clause of SELECT statement in
the SQL property.
If SELECT has no WHERE clause, AddWhere creates it.
Note: the AddWhere method is implicitly called by RefreshRecord. The AddWhere method
works for the SELECT statements only.
Note: the AddWhere method adds a value to the WHERE condition as is. If you expect thisvalue to be enclosed in brackets, you should bracket it explicitly.

See Also
DeleteWhere© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.5.3.2 BreakExec Method

Breaks execution of a SQL statement on the server.

Class
TCustomDADataSet

Syntax
procedure BreakExec; virtual;

Remarks© 2019 Devart

Provide Feedback

360

SQL Server Data Access Components

Call the BreakExec method to break execution of a SQL statement on the server.
It makes sense to call BreakExec only from another thread.
Also you should remeber that calling BreakExec to interrupt dataset opening in the
NonBlocking mode may not have effect if fetch has already begun (this happens when
BreakExec falls between two fetch operations).

See Also
TCustomDADataSet.Execute
TMSConnection.OnInfoMessage
TMSSQL.BreakExec© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.3 CreateBlobStream Method

Used to obtain a stream for reading data from or writing data to a BLOB field, specified by the
Field parameter.

Class
TCustomDADataSet

Syntaxfunction CreateBlobStream(Field: TField; Mode: TBlobStreamMode):
TStream; override;
Parameters
Field
Holds the BLOB field for reading data from or writing data to from a stream.
Mode
Holds the stream mode, for which the stream will be used.
Return Value
The BLOB Stream.

Remarks
Call the CreateBlobStream method to obtain a stream for reading data from or writing data toa BLOB field, specified by the Field parameter. It must be a TBlobField component. You canspecify whether the stream will be used for reading, writing, or updating the contents of the
field with the Mode parameter.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference361

Devart. All Rights
Reserved.
5.10.1.5.3.4 DeleteWhere Method

Removes WHERE clause from the SQL property and assigns the BaseSQL property.

Class
TCustomDADataSet

Syntax
procedure DeleteWhere;

Remarks
Call the DeleteWhere method to remove WHERE clause from the the SQL property andassign BaseSQL.

See Also
AddWhere
BaseSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.5 Execute Method

Executes a SQL statement on the server.

Class
TCustomDADataSet

Overload List
Name
ExecuteExecute(Iters: integer; Offset: integer)© 1997-2019
Request Support
Devart. All Rights
Reserved.

© 2019 Devart

Description
Executes a SQL statement on the server.
Used to perform Batch operations .
DAC Forum

Provide Feedback

362

SQL Server Data Access Components

Executes a SQL statement on the server.

Class
TCustomDADataSet

Syntax
procedure Execute; overload; virtual;

Remarks
Call the Execute method to execute an SQL statement on the server. If SQL statement is a
SELECT query, Execute calls the Open method.
Execute implicitly prepares SQL statement by calling the TCustomDADataSet.Prepare
method if the TCustomDADataSet.Options option is set to True and the statement has notbeen prepared yet. To speed up the performance in case of multiple Execute calls, anapplication should call Prepare before calling the Execute method for the first time.

See Also
TCustomDADataSet.AfterExecute
TCustomDADataSet.Executing
TCustomDADataSet.Prepare© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Used to perform Batch operations .

Class
TCustomDADataSet

Syntax
procedure Execute(Iters: integer; Offset: integer = 0); overload;
virtual;Parameters
Iters
Specifies the number of inserted rows.
OffsetPoints the array element, which the Batch operation starts from. 0 by default.

© 2019 DevartReference

363

Remarks
The Execute method executes the specified batch SQL query. See the Batch operations
article for samples.

See Also
Batch operations© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.6 Executing Method

Indicates whether SQL statement is still being executed.

Class
TCustomDADataSet

Syntaxfunction Executing: boolean;
Return Value
True, if SQL statement is still being executed.

Remarks
Check Executing to learn whether TCustomDADataSet is still executing SQL statement. Use
the Executing method if NonBlocking is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.7 Fetched Method

Used to learn whether TCustomDADataSet has already fetched all rows.

Class
TCustomDADataSet

Syntaxfunction Fetched: boolean; virtual;
Return Value© 2019 Devart

364

SQL Server Data Access Components

True, if all rows are fetched.

Remarks
Check Fetched to learn whether TCustomDADataSet has already fetched all rows.

See Also
Fetching© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.8 Fetching Method

Used to learn whether TCustomDADataSet is still fetching rows.

Class
TCustomDADataSet

Syntaxfunction Fetching: boolean;
Return Value
True, if TCustomDADataSet is still fetching rows.

Remarks
Check Fetching to learn whether TCustomDADataSet is still fetching rows. Use the Fetching
method if NonBlocking is True.

See Also
Executing© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.9 FetchingAll Method

Used to learn whether TCustomDADataSet is fetching all rows to the end.

Class
TCustomDADataSet

Syntax© 2019 DevartReference

365

function FetchingAll: boolean;
Return Value
True, if TCustomDADataSet is fetching all rows to the end.

Remarks
Check FetchingAll to learn whether TCustomDADataSet is fetching all rows to the end.

See Also
Executing© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.10 FindKey Method

Searches for a record which contains specified field values.

Class
TCustomDADataSet

Syntaxfunction FindKey(const KeyValues: array of System.TVarRec):
Boolean;Parameters
KeyValues
Holds a key.

Remarks
Call the FindKey method to search for a specific record in a dataset. KeyValues holds a
comma-delimited array of field values, that is called a key.
This function is provided for BDE compatibility only. It is recommended to use functions
TMemDataSet.Locate and TMemDataSet.LocateEx for the record search.

© 1997-2019
Devart. All Rights
Reserved.
5.10.1.5.3.11 FindMacro MethodClass© 2019 Devart

Request Support

DAC Forum

Provide Feedback

366

SQL Server Data Access Components

TCustomDADataSet

Syntaxfunction FindMacro(const Value: string): TMacro;Parameters
Value

See Also
TMacroMacrosMacroByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.12 FindNearest Method

Moves the cursor to a specific record or to the first record in the dataset that matches or isgreater than the values specified in the KeyValues parameter.

Class
TCustomDADataSet

Syntax
procedure FindNearest(const KeyValues: array of System.TVarRec);
Parameters
KeyValues
Holds the values of the record key fields to which the cursor should be moved.

Remarks
Call the FindNearest method to move the cursor to a specific record or to the first record in
the dataset that matches or is greater than the values specified in the KeyValues parameter. If
there are no records that match or exceed the specified criteria, the cursor will not move.
This function is provided for BDE compatibility only. It is recommended to use functions
TMemDataSet.Locate and TMemDataSet.LocateEx for the record search.

See Also
TMemDataSet.Locate© 2019 DevartReference

367

TMemDataSet.LocateEx
FindKey© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.13 FindParam Method

Determines if a parameter with the specified name exists in a dataset.

Class
TCustomDADataSet

Syntaxfunction FindParam(const Value: string): TDAParam;
Parameters
Value
Holds the name of the param for which to search.
Return Valuethe TDAParam object for the specified Name. Otherwise it returns nil.

Remarks
Call the FindParam method to determine if a specified param component exists in a dataset.
Name is the name of the param for which to search. If FindParam finds a param with amatching name, it returns a TDAParam object for the specified Name. Otherwise it returns
nil.

See Also
ParamsParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.14 GetDataType Method

Returns internal field types defined in the MemData and accompanying modules.

Class
TCustomDADataSet© 2019 Devart

368

SQL Server Data Access Components

Syntaxfunction GetDataType(const FieldName: string): integer; virtual;Parameters
FieldName
Holds the name of the field.
Return Value
internal field types defined in MemData and accompanying modules.

Remarks
Call the GetDataType method to return internal field types defined in the MemData andaccompanying modules. Internal field data types extend the TFieldType type of VCL by
specific database server data types. For example, ftString, ftFile, ftObject.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.15 GetFieldObject Method

Returns a multireference shared object from field.

Class
TCustomDADataSet

Syntaxfunction GetFieldObject(Field: TField): TSharedObject;
overload;function GetFieldObject(Field: TField; RecBuf:
TRecordBuffer): TSharedObject; overload;function
GetFieldObject(FieldDesc: TFieldDesc): TSharedObject;
overload;function GetFieldObject(FieldDesc: TFieldDesc; RecBuf:
TRecordBuffer): TSharedObject; overload;function
GetFieldObject(const FieldName: string): TSharedObject; overload;
Parameters
FieldName
Holds the field name.
Return Value
multireference shared object.

Remarks© 2019 DevartReference369

Call the GetFieldObject method to return a multireference shared object from field. If field
does not hold one of the TSharedObject descendants, GetFieldObject raises an exception.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.16 GetFieldPrecision Method

Retrieves the precision of a number field.

Class
TCustomDADataSet

Syntaxfunction GetFieldPrecision(const FieldName: string): integer;
Parameters
FieldName
Holds the existing field name.
Return Value
precision of number field.

Remarks
Call the GetFieldPrecision method to retrieve the precision of a number field. FieldName is thename of an existing field.

See Also
GetFieldScale© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.17 GetFieldScale Method

Retrieves the scale of a number field.

Class
TCustomDADataSet

Syntaxfunction GetFieldScale(const FieldName: string): integer;© 2019 Devart

370

SQL Server Data Access Components

Parameters
FieldName
Holds the existing field name.
Return Valuethe scale of the number field.

Remarks
Call the GetFieldScale method to retrieve the scale of a number field. FieldName is the nameof an existing field.

See Also
GetFieldPrecision© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.18 GetKeyFieldNames Method

Provides a list of available key field names.

Class
TCustomDADataSet

Syntax
procedure GetKeyFieldNames(List: TStrings);
Parameters
List
The list of available key field names
Return Value
Key field name

Remarks
Call the GetKeyFieldNames method to get the names of available key fields. Populates astring list with the names of key fields in tables.

See Also
TCustomDAConnection.GetTableNames
TCustomDAConnection.GetStoredProcNames© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference371

Devart. All Rights
Reserved.
5.10.1.5.3.19 GetOrderBy Method

Retrieves an ORDER BY clause from a SQL statement.

Class
TCustomDADataSet

Syntaxfunction GetOrderBy: string;
Return Valuean ORDER BY clause from the SQL statement.

Remarks
Call the GetOrderBy method to retrieve an ORDER BY clause from a SQL statement.
Note: GetOrderBy and SetOrderBy methods serve to process only quite simple queries anddon't support, for example, subqueries.

See Also
SetOrderBy© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.20 GotoCurrent Method

Sets the current record in this dataset similar to the current record in another dataset.

Class
TCustomDADataSet

Syntax
procedure GotoCurrent(DataSet: TCustomDADataSet);
Parameters
DataSetHolds the TCustomDADataSet descendant to synchronize the record position with.

Remarks© 2019 Devart

372

SQL Server Data Access Components

Call the GotoCurrent method to set the current record in this dataset similar to the current
record in another dataset. The key fields in both these DataSets must be coincident.

See Also
TMemDataSet.Locate
TMemDataSet.LocateEx© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.21 Lock Method

Locks the current record.

Class
TCustomDADataSet

Syntax
procedure Lock; virtual;

Remarks
Call the Lock method to lock the current record by executing the statement that is defined in
the SQLLock property.
The Lock method sets the savepoint with the name LOCK_ + <component_name>.

See Also
UnLock© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.22 MacroByName Method

Finds a Macro with the name passed in Name.

Class
TCustomDADataSet

Syntaxfunction MacroByName(const Value: string): TMacro;© 2019 DevartReference

373

Parameters
Value
Holds the name of the Macro to search for.
Return Value
the Macro, if a match was found.

Remarks
Call the MacroByName method to find a Macro with the name passed in Name. If a match
was found, MacroByName returns the Macro. Otherwise, an exception is raised. Use thismethod rather than a direct reference to the Items property to avoid depending on the order ofthe entries.
To locate a parameter by name without raising an exception if the parameter is not found, use
the FindMacro method.
To assign the value of macro use the TMacro.Value property.

ExampleMSQuery.SQL:= 'SELECT * FROM Scott.Dept ORDER BY &Order';MSQuery.MacroByName('Order').Value:= 'DeptNo';
MSQuery.Open;

See Also
TMacroMacrosFindMacro© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.23 ParamByName Method

Sets or uses parameter information for a specific parameter based on its name.

Class
TCustomDADataSet

Syntaxfunction ParamByName(const Value: string): TDAParam;
Parameters
Value© 2019 Devart

374

SQL Server Data Access Components

Holds the name of the parameter for which to retrieve information.
Return Valuea TDAParam object.

Remarks
Call the ParamByName method to set or use parameter information for a specific parameterbased on its name. Name is the name of the parameter for which to retrieve information.
ParamByName is used to set a parameter's value at runtime and returns a TDAParamobject.

ExampleThe following statement retrieves the current value of a parameter called "Contact" into anedit box:
Edit1.Text := Query1.ParamsByName('Contact').AsString;See Also
ParamsFindParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.24 Prepare Method

Allocates, opens, and parses cursor for a query.

Class
TCustomDADataSet

Syntax
procedure Prepare; override;

Remarks
Call the Prepare method to allocate, open, and parse cursor for a query. Calling Prepare
before executing a query improves application performance.
SQL statements which have output parameters and aren't stored procedures calls or someof system functions such as sp_setapprole, should be executed without prior call to the
Prepare method.
The UnPrepare method unprepares a query.

© 2019 DevartReference

375

Note: When you change the text of a query at runtime, the query is automatically closed andunprepared.

See Also
TMemDataSet.Prepared
TMemDataSet.UnPrepare
Options© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.25 RefreshRecord Method

Actualizes field values for the current record.

Class
TCustomDADataSet

Syntax
procedure RefreshRecord;

Remarks
Call the RefreshRecord method to actualize field values for the current record.
RefreshRecord performs query to database and refetches new field values from the returned
cursor.

See Also
RefreshOptions
SQLRefresh© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.5.3.26 RestoreSQL Method

Restores the SQL property modified by AddWhere and SetOrderBy.

Class
TCustomDADataSet

Syntax© 2019 Devart

Provide Feedback

376

SQL Server Data Access Components

procedure RestoreSQL;

Remarks
Call the RestoreSQL method to restore the SQL property modified by AddWhere and
SetOrderBy.

See Also
AddWhere
SetOrderBy
SaveSQLSQLSaved© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.27 SaveSQL Method

Saves the SQL property value to BaseSQL.

Class
TCustomDADataSet

Syntax
procedure SaveSQL;

Remarks
Call the SaveSQL method to save the SQL property value to the BaseSQL property.

See Also
SQLSaved
RestoreSQLBaseSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

377

5.10.1.5.3.28 SetOrderBy Method

Builds an ORDER BY clause of a SELECT statement.

Class
TCustomDADataSet

Syntax
procedure SetOrderBy(const Fields: string);
Parameters
FieldsHolds the names of the fields which will be added to the ORDER BY clause.

Remarks
Call the SetOrderBy method to build an ORDER BY clause of a SELECT statement. The
fields are identified by the comma-delimited field names.
Note: The GetOrderBy and SetOrderBy methods serve to process only quite simple queries
and don't support, for example, subqueries.

ExampleQuery1.SetOrderBy('DeptNo;DName');See Also
GetOrderBy© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.29 SQLSaved Method

Determines if the SQL property value was saved to the BaseSQL property.

Class
TCustomDADataSet

Syntaxfunction SQLSaved: boolean;
Return Value
True, if the SQL property value was saved to the BaseSQL property.
© 2019 Devart

378

SQL Server Data Access Components

Remarks
Call the SQLSaved method to know whether the SQL property value was saved to the
BaseSQL property.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.3.30 UnLock Method

Releases a record lock.

Class
TCustomDADataSet

Syntax
procedure UnLock;

Remarks
Call the Unlock method to release the record lock made by the Lock method before.
Unlock is performed by rolling back to the savepoint set by the Lock method.

See Also
Lock© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.4 Events

Events of the TCustomDADataSet class.
For a complete list of the TCustomDADataSet class members, see the TCustomDADataSet
Members topic.

PublicName
AfterExecute
AfterFetch

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
© 2019 DevartReference

AfterUpdateExecute

BeforeFetch

BeforeUpdateExecute

OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)

379

Occurs after executing
insert, delete, update, lockand refresh operations.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lock,and refresh operations.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.

See Also
TCustomDADataSet Class
TCustomDADataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.4.1 AfterExecute Event

Occurs after a component has executed a query to database.

Class
TCustomDADataSet

Syntaxproperty AfterExecute: TAfterExecuteEvent;Remarks
Occurs after a component has executed a query to database.

See Also
TCustomDADataSet.Execute© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

380

SQL Server Data Access Components

Reserved.
5.10.1.5.4.2 AfterFetch Event

Occurs after dataset finishes fetching data from server.

Class
TCustomDADataSet

Syntaxproperty AfterFetch: TAfterFetchEvent;Remarks
The AfterFetch event occurs after dataset finishes fetching data from server.
Note: In TCustomMSDataSet.Options mode this event occurs in context of calling thread.

See Also
BeforeFetch
TMSDataSetOptions.NonBlocking© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.4.3 AfterUpdateExecute Event

Occurs after executing insert, delete, update, lock and refresh operations.

Class
TCustomDADataSet

Syntaxproperty AfterUpdateExecute: TUpdateExecuteEvent;Remarks
Occurs after executing insert, delete, update, lock, and refresh operations. You can use
AfterUpdateExecute to set the parameters of corresponding statements.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference381

5.10.1.5.4.4 BeforeFetch Event

Occurs before dataset is going to fetch block of records from the server.

Class
TCustomDADataSet

Syntaxproperty BeforeFetch: TBeforeFetchEvent;Remarks
The BeforeFetch event occurs every time before dataset is going to fetch a block of records
from the server. Set Cancel to True to abort current fetch operation.
Note: In TCustomMSDataSet.Options mode event handler is called from the fetching thread.
Therefore, if you have set NonBlocking property to True, you should use threadsynchronization mechanisms in the code of BeforeFetch event handler.

See Also
AfterFetch
TMSDataSetOptions.NonBlocking© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.5.4.5 BeforeUpdateExecute Event

Occurs before executing insert, delete, update, lock, and refresh operations.

Class
TCustomDADataSet

Syntaxproperty BeforeUpdateExecute: TUpdateExecuteEvent;Remarks
Occurs before executing insert, delete, update, lock, and refresh operations. You can use
BeforeUpdateExecute to set the parameters of corresponding statements.

See Also
AfterUpdateExecute© 2019 Devart

382

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6 TCustomDASQL ClassA base class for components executing SQL statements that do not return result sets.
For a list of all members of this type, see TCustomDASQL members.

Unit
DBAccess

SyntaxTCustomDASQL = class(TComponent);

Remarks
TCustomDASQL is a base class that defines functionality for descendant classes whichaccess database using SQL statements. Applications never use TCustomDASQL objects
directly. Instead they use descendants of TCustomDASQL.
Use TCustomDASQL when client application must execute SQL statement or call stored
procedure on the database server. The SQL statement should not retrieve rows from thedatabase.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.1 Members

TCustomDASQL class overview.

Properties
Name
ChangeCursor

Connection

Debug

Description
Enables or disables
changing screen cursor
when executing commandsin the NonBlocking mode.
Used to specify aconnection object to use toconnect to a data store.
Used to display executing
statement, all its parameters'
values, and the type of© 2019 DevartReference

FinalSQL

MacroCount
MacrosParamCheck

ParamCount
ParamsParamValues

Prepared

RowsAffected

SQL

383

parameters.
Used to return a SQL
statement with expanded
macros.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify whether
parameters for the Params
property are implicitly
generated when the SQL
property is being changed.
Indicates the number ofparameters in the Params
property.
Used to contain parameters
for a SQL statement.
Used to get or set the valuesof individual fieldparameters that are
identified by name.
Used to indicate whether aquery is prepared forexecution.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
Used to provide a SQL
statement that a
TCustomDASQL
component executes when
the Execute method iscalled.

Methods
Name
Execute© 2019 Devart

Description
Overloaded. Executes a
SQL statement on theserver.

384

SQL Server Data Access Components

Checks whether
TCustomDASQL still
executes a SQL statement.
Searches for a macro withthe specified name.
Finds a parameter with thespecified name.
Finds a Macro with thename passed in Name.
Finds a parameter with thespecified name.
Allocates, opens, andparses cursor for a query.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Waits until TCustomDASQL
executes a SQL statement.

Executing
FindMacro
FindParam
MacroByName
ParamByName
Prepare

UnPrepare

WaitExecuting

EventsName

Description
Occurs after a SQL
statement has been
executed.

AfterExecute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2 Properties

Properties of the TCustomDASQL class.
For a complete list of the TCustomDASQL class members, see the TCustomDASQLMembers topic.

PublicName
ChangeCursor

Description
Enables or disables
changing screen cursor
when executing commandsin the NonBlocking mode.
© 2019 DevartReference

Connection

Debug

FinalSQL

MacroCount
MacrosParamCheck

ParamCount
ParamsParamValues

Prepared

RowsAffected

SQL

See Also© 2019 Devart

385

Used to specify aconnection object to use toconnect to a data store.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to return a SQL
statement with expanded
macros.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify whether
parameters for the Params
property are implicitly
generated when the SQL
property is being changed.
Indicates the number ofparameters in the Params
property.
Used to contain parameters
for a SQL statement.
Used to get or set the valuesof individual fieldparameters that are
identified by name.
Used to indicate whether aquery is prepared forexecution.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
Used to provide a SQL
statement that a
TCustomDASQL
component executes when
the Execute method iscalled.

386

SQL Server Data Access Components

TCustomDASQL Class
TCustomDASQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.1 ChangeCursor Property

Enables or disables changing screen cursor when executing commands in the NonBlocking
mode.

Class
TCustomDASQL

Syntaxproperty ChangeCursor: boolean;

Remarks
Set the ChangeCursor property to False to prevent the screen cursor from changing to
crSQLArrow when executing commands in the NonBlocking mode. The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.2 Connection Property

Used to specify a connection object to use to connect to a data store.

Class
TCustomDASQL

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomDAConnection or its
descendant class objects.
At runtime, link an instance of a TCustomDAConnection descendant to the Connection© 2019 DevartReference387

property.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.3 Debug Property

Used to display executing statement, all its parameters' values, and the type of parameters.

Class
TCustomDASQL

Syntaxproperty Debug: boolean default False;

Remarks
Set the Debug property to True to display executing statement and all its parameters' values.
Also displays the type of parameters.
You should add the SdacVcl unit to the uses clause of any unit in your project to make the
Debug property work.
Note: If TMSSQLMonitor is used in the project and the TMSSQLMonitor.Active property is set
to False, the debug window is not displayed.

See Also
TCustomDADataSet.Debug© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.6.2.4 FinalSQL Property

Used to return a SQL statement with expanded macros.

Class
TCustomDASQL

Syntaxproperty FinalSQL: string;

Remarks© 2019 Devart

Provide Feedback

388

SQL Server Data Access Components

Read the FinalSQL property to return a SQL statement with expanded macros. This is theexact statement that will be passed on to the database server.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.5 MacroCount Property

Used to get the number of macros associated with the Macros property.

Class
TCustomDASQL

Syntaxproperty MacroCount: word;

Remarks
Use the MacroCount property to get the number of macros associated with the Macrosproperty.

See Also
Macros© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.6 Macros Property

Makes it possible to change SQL queries easily.

Class
TCustomDASQL

Syntaxproperty Macros: TMacros stored False;

Remarks
With the help of macros you can easily change SQL query text at design- or runtime. Marcos
extend abilities of parameters and allow to change conditions in a WHERE clause or sortorder in an ORDER BY clause. You just insert &MacroName in the SQL query text and© 2019 DevartReference389

change value of macro in the Macro property editor at design time or call the MacroByName
function at run time. At the time of opening the query macro is replaced by its value.

See Also
TMacroMacroByName
Params© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.7 ParamCheck Property

Used to specify whether parameters for the Params property are implicitly generated when
the SQL property is being changed.

Class
TCustomDASQL

Syntaxproperty ParamCheck: boolean default True;

Remarks
Use the ParamCheck property to specify whether parameters for the Params property are
implicitly generated when the SQL property is being changed.
Set ParamCheck to True to let TCustomDASQL generate the Params property for thedataset based on a SQL statement automatically.
Setting ParamCheck to False can be used if the dataset component passes to a server the
DDL statements that contain, for example, declarations of the stored procedures that will
accept parameterized values themselves. The default value is True.

See Also
Params© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

390

SQL Server Data Access Components

5.10.1.6.2.8 ParamCount Property

Indicates the number of parameters in the Params property.

Class
TCustomDASQL

Syntaxproperty ParamCount: word;

Remarks
Use the ParamCount property to determine how many parameters are there in the Params
property.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.9 Params Property

Used to contain parameters for a SQL statement.

Class
TCustomDASQL

Syntaxproperty Params: TDAParams stored False;

Remarks
Access the Params property at runtime to view and set parameter names, values, and datatypes dynamically (at design-time use the Parameters editor to set parameter properties).
Params is a zero-based array of parameter records. Index specifies the array element toaccess. An easier way to set and retrieve parameter values when the name of eachparameter is known is to call ParamByName.

ExampleSetting parameters at runtime:procedure TForm1.Button1Click(Sender: TObject);
beginwith MSSQL do
begin© 2019 DevartReference

391

SQL.Clear;
SQL.Add('INSERT INTO Temp_Table(Id, Name)');SQL.Add('VALUES (:id, :Name)');ParamByName('Id').AsInteger := 55;
Params[1].AsString := ' Green';
Execute;end;
end;

See Also
TDAParam
FindParam
Macros© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.10 ParamValues Property(Indexer)

Used to get or set the values of individual field parameters that are identified by name.

Class
TCustomDASQL

Syntaxproperty ParamValues[const ParamName: string]: Variant; default;
Parameters
ParamName
Holds parameter names separated by semicolon.

Remarks
Use the ParamValues property to get or set the values of individual field parameters that are
identified by name.
Setting ParamValues sets the Value property for each parameter listed in the ParamName
string. Specify the values as Variants.
Getting ParamValues retrieves an array of variants, each of which represents the value of oneof the named parameters.
Note: The Params array is generated implicitly if ParamCheck property is set to True. If
ParamName includes a name that does not match any of the parameters in Items, an
exception is raised.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

392

SQL Server Data Access Components

Reserved.
5.10.1.6.2.11 Prepared Property

Used to indicate whether a query is prepared for execution.

Class
TCustomDASQL

Syntaxproperty Prepared: boolean;

Remarks
Check the Prepared property to determine if a query is already prepared for execution. Truemeans that the query has already been prepared. As a rule prepared queries are executed
faster, but the preparation itself also takes some time. One of the proper cases for using
preparation is parametrized queries that are executed several times.

See Also
Prepare© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.2.12 Row sAffected Property

Used to indicate the number of rows which were inserted, updated, or deleted during the lastquery operation.

Class
TCustomDASQL

Syntaxproperty RowsAffected: integer;

Remarks
Check RowsAffected to determine how many rows were inserted, updated, or deleted during
the last query operation. If RowsAffected is -1, the query has not inserted, updated, or deleted
any rows.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference393

Devart. All Rights
Reserved.
5.10.1.6.2.13 SQL Property

Used to provide a SQL statement that a TCustomDASQL component executes when the
Execute method is called.

Class
TCustomDASQL

Syntaxproperty SQL: TStrings;

Remarks
Use the SQL property to provide a SQL statement that a TCustomDASQL component
executes when the Execute method is called. At design time the SQL property can be edited
by invoking the String List editor in Object Inspector.

See Also
FinalSQL
TCustomDASQL.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3 Methods

Methods of the TCustomDASQL class.
For a complete list of the TCustomDASQL class members, see the TCustomDASQLMembers topic.

PublicName
ExecuteExecuting
FindMacro© 2019 Devart

Description
Overloaded. Executes a
SQL statement on theserver.
Checks whether
TCustomDASQL still
executes a SQL statement.
Searches for a macro with394

SQL Server Data Access Components

the specified name.
Finds a parameter with thespecified name.
Finds a Macro with thename passed in Name.
Finds a parameter with thespecified name.
Allocates, opens, andparses cursor for a query.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Waits until TCustomDASQL
executes a SQL statement.

FindParam
MacroByName
ParamByName
Prepare

UnPrepare

WaitExecuting

See Also
TCustomDASQL Class
TCustomDASQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.1 Execute Method

Executes a SQL statement on the server.

Class
TCustomDASQL

Overload List
Name
ExecuteExecute(Iters: integer; Offset: integer)© 1997-2019
Request Support
Devart. All Rights
Reserved.

Description
Executes a SQL statement on the server.
Used to perform Batch operations .
DAC Forum

Provide Feedback

Executes a SQL statement on the server.

Class© 2019 DevartReference

395

TCustomDASQL

Syntax
procedure Execute; overload; virtual;

Remarks
Call the Execute method to execute a SQL statement on the server. If the SQL statement has
OUT parameters, use the TCustomDASQL.ParamByName method or the
TCustomDASQL.Params property to get their values. Iters argument specifies the number oftimes this statement is executed for the DML array operations.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Used to perform Batch operations .

Class
TCustomDASQL

Syntax
procedure Execute(Iters: integer; Offset: integer = 0); overload;
virtual;Parameters
Iters
Specifies the number of inserted rows.
OffsetPoints the array element, which the Batch operation starts from. 0 by default.

Remarks
The Execute method executes the specified batch SQL query. See the Batch operations
article for samples.

See Also
Batch operations© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

396

SQL Server Data Access Components

5.10.1.6.3.2 Executing Method

Checks whether TCustomDASQL still executes a SQL statement.

Class
TCustomDASQL

Syntaxfunction Executing: boolean;
Return Value
True, if a SQL statement is still being executed by TCustomDASQL.

Remarks
Check Executing to find out whether TCustomDASQL still executes a SQL statement. The
Executing method is used for nonblocking execution.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.3 FindMacro Method

Searches for a macro with the specified name.

Class
TCustomDASQL

Syntaxfunction FindMacro(const Value: string): TMacro;Parameters
Value
Holds the name of a macro to search for.
Return Valuethe TMacro object, if a macro with the specified name has been found. If it has not, returns
nil.

Remarks
Call the FindMacro method to find a macro with the specified name in a dataset.

See Also© 2019 DevartReference

397

TMacroMacrosMacroByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.4 FindParam Method

Finds a parameter with the specified name.

Class
TCustomDASQL

Syntaxfunction FindParam(const Value: string): TDAParam;
Parameters
Value
Holds the parameter name to search for.
Return Valuea TDAParm object, if a parameter with the specified name has been found. If it has not,returns nil.

Remarks
Call the FindParam method to find a parameter with the specified name in a dataset.

See Also
ParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.6.3.5 MacroByName Method

Finds a Macro with the name passed in Name.

Class
TCustomDASQL

Syntax© 2019 Devart

DAC Forum

Provide Feedback

398

SQL Server Data Access Components

function MacroByName(const Value: string): TMacro;Parameters
Value
Holds the name of the Macro to search for.
Return Value
the Macro, if a match was found.

Remarks
Call the MacroByName method to find a Macro with the name passed in Name. If a match
was found, MacroByName returns the Macro. Otherwise, an exception is raised. Use thismethod rather than a direct reference to the Items property to avoid depending on the order ofthe entries.
To locate a parameter by name without raising an exception if the parameter is not found, use
the FindMacro method.
To assign the value of macro use the TMacro.Value property.

See Also
TMacroMacrosFindMacro© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.6 ParamByName Method

Finds a parameter with the specified name.

Class
TCustomDASQL

Syntaxfunction ParamByName(const Value: string): TDAParam;
Parameters
Value
Holds the name of the parameter to search for.
Return Valuea TDAParam object, if a match was found. Otherwise, an exception is raised.

© 2019 DevartReference

399

Remarks
Use the ParamByName method to find a parameter with the specified name. If no parameterwith the specified name found, an exception is raised.

ExampleMSSQL.Execute;Edit1.Text := MSSQL.ParamsByName('Contact').AsString;See Also
FindParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.7 Prepare Method

Allocates, opens, and parses cursor for a query.

Class
TCustomDASQL

Syntax
procedure Prepare; virtual;

Remarks
Call the Prepare method to allocate, open, and parse cursor for a query. Calling Prepare
before executing a query improves application performance.
SQL statements which have output parameters and aren't stored procedures calls or someof system functions such as sp_setapprole, should be executed without prior call to the
Prepare method.
The UnPrepare method unprepares a query.
Note: When you change the text of a query at runtime, the query is automatically closed andunprepared.

See Also
Prepared
UnPrepare© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

400

SQL Server Data Access Components

Reserved.
5.10.1.6.3.8 UnPrepare Method

Frees the resources allocated for a previously prepared query on the server and client sides.

Class
TCustomDASQL

Syntax
procedure UnPrepare; virtual;

Remarks
Call the UnPrepare method to free resources allocated for a previously prepared query on theserver and client sides.

See Also
Prepare© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.3.9 WaitExecuting Method

Waits until TCustomDASQL executes a SQL statement.

Class
TCustomDASQL

Syntaxfunction WaitExecuting(TimeOut: integer = 0): boolean;
Parameters
TimeOut
Holds the time in seconds to wait while TCustomDASQL executes the SQL statement. Zeromeans infinite time.
Return Value
True, if the execution of a SQL statement was completed in the preset time.

Remarks
Call the WaitExecuting method to wait until TCustomDASQL executes a SQL statement. Use© 2019 DevartReference

401

the WaitExecuting method for nonblocking execution.

See Also
Executing© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.4 Events

Events of the TCustomDASQL class.
For a complete list of the TCustomDASQL class members, see the TCustomDASQLMembers topic.

PublicName

Description
Occurs after a SQL
statement has been
executed.

AfterExecute

See Also
TCustomDASQL Class
TCustomDASQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.6.4.1 AfterExecute Event

Occurs after a SQL statement has been executed.

Class
TCustomDASQL

Syntaxproperty AfterExecute: TAfterExecuteEvent;Remarks
Occurs after a SQL statement has been executed. This event may be used for descendantcomponents which use multithreaded environment.

© 2019 Devart

402

SQL Server Data Access Components

See Also
TCustomDASQL.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7 TCustomDAUpdateSQL ClassA base class for components that provide DML statements for more flexible control over data
modifications.
For a list of all members of this type, see TCustomDAUpdateSQL members.

Unit
DBAccess

SyntaxTCustomDAUpdateSQL = class(TComponent);

Remarks
TCustomDAUpdateSQL is a base class for components that provide DML statements formore flexible control over data modifications. Besides providing BDE compatibility, thiscomponent allows to associate a separate component for each update command.

See Also
TCustomMSDataSet.UpdateObject© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.1 Members

TCustomDAUpdateSQL class overview.

Properties
Name
DataSetDescription
Used to hold a reference tothe TCustomDADataSet
object that is being updated.

DeleteObject

Provides ability to perform
advanced adjustment of the© 2019 DevartReference

403

delete operations.
Used when deleting arecord.
Provides ability to perform
advanced adjustment ofinsert operations.
Used when inserting arecord.
Provides ability to perform
advanced adjustment of lock
operations.
Used to lock the current
record.
Provides ability to perform
advanced adjustment ofmodify operations.
Used when updating arecord.
Provides ability to perform
advanced adjustment of
refresh operations.
Used to specify an SQL
statement that will be used
for refreshing the current
record byTCustomDADataSet.Refres
hRecord procedure.
Used to return a SQL
statement for one of the
ModifySQL, InsertSQL, orDeleteSQL properties.

DeleteSQL
InsertObject
InsertSQL
LockObject
LockSQL
ModifyObject
ModifySQL
RefreshObject

RefreshSQL

SQL

Methods
Name

Description
Sets parameters for a SQL
statement and executes it to
update a record.
Executes a SQL statement.

Apply
ExecSQL© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

404

SQL Server Data Access Components

5.10.1.7.2 Properties

Properties of the TCustomDAUpdateSQL class.
For a complete list of the TCustomDAUpdateSQL class members, see theTCustomDAUpdateSQL Members topic.

PublicName
DataSetSQL

Description
Used to hold a reference tothe TCustomDADataSet
object that is being updated.
Used to return a SQL
statement for one of the
ModifySQL, InsertSQL, orDeleteSQL properties.

Published
Name
DeleteObject
DeleteSQL
InsertObject
InsertSQL
LockObject
LockSQL
ModifyObject
ModifySQL
RefreshObject
RefreshSQL

Description
Provides ability to perform
advanced adjustment of thedelete operations.
Used when deleting arecord.
Provides ability to perform
advanced adjustment ofinsert operations.
Used when inserting arecord.
Provides ability to perform
advanced adjustment of lock
operations.
Used to lock the current
record.
Provides ability to perform
advanced adjustment ofmodify operations.
Used when updating arecord.
Provides ability to perform
advanced adjustment of
refresh operations.
Used to specify an SQL© 2019 DevartReference

405

statement that will be used
for refreshing the current
record byTCustomDADataSet.Refres
hRecord procedure.

See Also
TCustomDAUpdateSQL Class
TCustomDAUpdateSQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.1 DataSet Property

Used to hold a reference to the TCustomDADataSet object that is being updated.

Class
TCustomDAUpdateSQL

Syntaxproperty DataSet: TCustomDADataSet;

Remarks
The DataSet property holds a reference to the TCustomDADataSet object that is being
updated. Generally it is not used directly.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.2 DeleteObject Property

Provides ability to perform advanced adjustment of the delete operations.

Class
TCustomDAUpdateSQL

Syntaxproperty DeleteObject: TComponent;© 2019 Devart

406

SQL Server Data Access Components

Remarks
Assign SQL component or a TCustomMSDataSet descendant to this property to perform
advanced adjustment of the delete operations. In some cases this can give some additional
performance. Use the same principle to set the SQL property of an object as for setting the
DeleteSQL property.

See Also
DeleteSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.3 DeleteSQL Property

Used when deleting a record.

Class
TCustomDAUpdateSQL

Syntaxproperty DeleteSQL: TStrings;

Remarks
Set the DeleteSQL property to a DELETE statement to use when deleting a record.
Statements can be parameterized queries with parameter names corresponding to thedataset field names.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.4 InsertObject Property

Provides ability to perform advanced adjustment of insert operations.

Class
TCustomDAUpdateSQL

Syntaxproperty InsertObject: TComponent;© 2019 DevartReference

407

Remarks
Assign SQL component or TCustomMSDataSet descendant to this property to perform
advanced adjustment of insert operations. In some cases this can give some additional
performance. Set the SQL property of the object in the same way as used for the InsertSQL
property.

See Also
InsertSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.5 InsertSQL Property

Used when inserting a record.

Class
TCustomDAUpdateSQL

Syntaxproperty InsertSQL: TStrings;

Remarks
Set the InsertSQL property to an INSERT INTO statement to use when inserting a record.
Statements can be parameterized queries with parameter names corresponding to thedataset field names.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.7.2.6 LockObject Property

Provides ability to perform advanced adjustment of lock operations.

Class
TCustomDAUpdateSQL

Syntaxproperty LockObject: TComponent;© 2019 Devart

Provide Feedback

408

SQL Server Data Access Components

Remarks
Assign a SQL component or TCustomMSDataSet descendant to this property to perform
advanced adjustment of lock operations. In some cases that can give some additional
performance. Set the SQL property of an object in the same way as used for the LockSQL
property.

See Also
LockSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.7 LockSQL Property

Used to lock the current record.

Class
TCustomDAUpdateSQL

Syntaxproperty LockSQL: TStrings;

Remarks
Use the LockSQL property to lock the current record. Statements can be parameterized
queries with parameter names corresponding to the dataset field names.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.8 ModifyObject Property

Provides ability to perform advanced adjustment of modify operations.

Class
TCustomDAUpdateSQL

Syntaxproperty ModifyObject: TComponent;

Remarks© 2019 DevartReference

409

Assign a SQL component or TCustomMSDataSet descendant to this property to perform
advanced adjustment of modify operations. In some cases this can give some additional
performance. Set the SQL property of the object in the same way as used for the ModifySQL
property.

See Also
ModifySQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.9 ModifySQL Property

Used when updating a record.

Class
TCustomDAUpdateSQL

Syntaxproperty ModifySQL: TStrings;

Remarks
Set ModifySQL to an UPDATE statement to use when updating a record. Statements can beparameterized queries with parameter names corresponding to the dataset field names.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.10 RefreshObject Property

Provides ability to perform advanced adjustment of refresh operations.

Class
TCustomDAUpdateSQL

Syntaxproperty RefreshObject: TComponent;

Remarks
Assign a SQL component or TCustomMSDataSet descendant to this property to perform© 2019 Devart

410

SQL Server Data Access Components

advanced adjustment of refresh operations. In some cases that can give some additional
performance. Set the SQL property of the object in the same way as used for theRefreshSQL property.

See Also
RefreshSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.11 RefreshSQL Property

Used to specify an SQL statement that will be used for refreshing the current record by
TCustomDADataSet.RefreshRecord procedure.

Class
TCustomDAUpdateSQL

Syntaxproperty RefreshSQL: TStrings;

Remarks
Use the RefreshSQL property to specify a SQL statement that will be used for refreshing thecurrent record by the TCustomDADataSet.RefreshRecord procedure.
You can assign to SQLRefresh a WHERE clause only. In such a case it is added to SELECT
defined by the SQL property by TCustomDADataSet.AddWhere.
To create a RefreshSQL statement at design time, use the query statements editor.

See Also
TCustomDADataSet.RefreshRecord© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.2.12 SQL Property(Indexer)

Used to return a SQL statement for one of the ModifySQL, InsertSQL, or DeleteSQL
properties.

Class
TCustomDAUpdateSQL© 2019 DevartReference

411

Syntaxproperty SQL[UpdateKind: TUpdateKind]: TStrings;
Parameters
UpdateKind
Specifies which of update SQL statements to return.

Remarks
Returns a SQL statement for one of the ModifySQL, InsertSQL, or DeleteSQL properties,
depending on the value of the UpdateKind index.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.3 Methods

Methods of the TCustomDAUpdateSQL class.
For a complete list of the TCustomDAUpdateSQL class members, see theTCustomDAUpdateSQL Members topic.

PublicName

Description
Sets parameters for a SQL
statement and executes it to
update a record.
Executes a SQL statement.

Apply
ExecSQL

See Also
TCustomDAUpdateSQL Class
TCustomDAUpdateSQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.3.1 Apply Method

Sets parameters for a SQL statement and executes it to update a record.

Class
TCustomDAUpdateSQL© 2019 Devart

412

SQL Server Data Access Components

Syntax
procedure Apply(UpdateKind: TUpdateKind); virtual;Parameters
UpdateKind
Specifies which of update SQL statements to execute.

Remarks
Call the Apply method to set parameters for a SQL statement and execute it to update arecord. UpdateKind indicates which SQL statement to bind and execute.
Apply is primarily intended for manually executing update statements from an
OnUpdateRecord event handler.
Note: If a SQL statement does not contain parameters, it is more efficient to call ExecSQL
instead of Apply.

See Also
ExecSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.7.3.2 ExecSQL Method

Executes a SQL statement.

Class
TCustomDAUpdateSQL

Syntax
procedure ExecSQL(UpdateKind: TUpdateKind);Parameters
UpdateKind
Specifies the kind of update statement to be executed.

Remarks
Call the ExecSQL method to execute a SQL statement, necessary for updating the records
belonging to a read-only result set when cached updates is enabled. UpdateKind specifies thestatement to execute.

© 2019 DevartReference

413

ExecSQL is primarily intended for manually executing update statements from theOnUpdateRecord event handler.
Note: To both bind parameters and execute a statement, call Apply.

See Also
Apply© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.8 TDACondition Class

Represents a condition from the TDAConditions list.
For a list of all members of this type, see TDACondition members.

Unit
DBAccess

SyntaxTDACondition = class(TCollectionItem);Remarks
Manipulate conditions using TDAConditions.

See Also
TDAConditions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.8.1 Members

TDACondition class overview.

Properties
Name

Name

Description
Indicates whether thecondition is enabled or not
The name of the condition

Value

The value of the condition

Enabled© 2019 Devart

414

SQL Server Data Access Components

Methods
Name
DisableDescription

EnableEnables the condition© 1997-2019
Devart. All Rights
Reserved.

Disables the condition

Request Support

DAC Forum

Provide Feedback

5.10.1.8.2 Properties

Properties of the TDACondition class.
For a complete list of the TDACondition class members, see the TDACondition Members
topic.

Published
Name

Name

Description
Indicates whether thecondition is enabled or not
The name of the condition

Value

The value of the condition

EnabledSee Also
TDACondition Class
TDACondition Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.8.2.1 Enabled Property

Indicates whether the condition is enabled or notClass
TDACondition

Syntaxproperty Enabled: Boolean default True;© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

415

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.10.1.8.2.2 Name Property

The name of the condition

Class
TDACondition

Syntaxproperty Name: string;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.8.2.3 Value Property

The value of the condition

Class
TDACondition

Syntaxproperty Value: string;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.8.3 Methods

Methods of the TDACondition class.
For a complete list of the TDACondition class members, see the TDACondition Members
topic.

PublicName
DisableDescription
Disables the condition

EnableEnables the condition© 2019 Devart

416

SQL Server Data Access Components

See Also
TDACondition Class
TDACondition Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.10.1.8.3.1 Disable Method

Disables the condition

Class
TDACondition

Syntax
procedure Disable;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.8.3.2 Enable Method

Enables the condition

Class
TDACondition

Syntax
procedure Enable;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.9 TDAConditions Class

Holds a collection of TDACondition objects.
For a list of all members of this type, see TDAConditions members.

Unit
DBAccess© 2019 DevartReference

417

SyntaxTDAConditions = class(TCollection);

Remarks
The given example code
UniTable1.Conditions.Add('1','JOB="MANAGER"');
UniTable1.Conditions.Add('2','SAL>2500');
UniTable1.Conditions.Enable;
UniTable1.Open;will return the following SQL:
SELECT * FROM EMP
WHERE (JOB="MANAGER")
and(SAL<2500)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.1 Members

TDAConditions class overview.

Properties
Name
Condition
Enabled
Items

Text

WhereSQL

Description
Used to iterate through all
the conditions.
Indicates whether thecondition is enabled
Used to iterate through allconditions.
The property returns
condition names and valuesas
CONDITION_NAME=CONDITION
Returns the SQL WHERE
condition added in theConditions property.

Methods
Name© 2019 Devart

Description

418

SQL Server Data Access Components

DeleteOverloaded. Adds a
condition to the WHERE
clause of the query.
Deletes the condition

DisableDisables the condition

EnableEnables the condition

Add

Search for TDACondition(the condition) by its name. If
found, the TDACondition
object is returned, otherwise- nil.
Retrieving a TDACondition
object by its name. If found,the TDACondition object isreturned, otherwise - anexception is raised.
Retrieving condition index by
its name. If found, thiscondition index is returned,
otherwise - the method
returns -1.
Removes the condition

Find

Get

IndexOf

Remove© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.2 Properties

Properties of the TDAConditions class.
For a complete list of the TDAConditions class members, see the TDAConditions Members
topic.

PublicName
Condition
Enabled
Items
Text

Description
Used to iterate through all
the conditions.
Indicates whether thecondition is enabled
Used to iterate through allconditions.
The property returns© 2019 DevartReference419

condition names and valuesas
CONDITION_NAME=CONDITION
Returns the SQL WHERE
condition added in theConditions property.

WhereSQL

See Also
TDAConditions Class
TDAConditions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.2.1 Condition Property(Indexer)

Used to iterate through all the conditions.

Class
TDAConditions

Syntaxproperty Condition[Index: Integer]: TDACondition;
Parameters
Index© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.10.1.9.2.2 Enabled Property

Indicates whether the condition is enabledClass
TDAConditions

Syntaxproperty Enabled: Boolean;© 1997-2019© 2019 Devart

Request Support

420

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.10.1.9.2.3 Items Property(Indexer)

Used to iterate through all conditions.

Class
TDAConditions

Syntaxproperty Items[Index: Integer]: TDACondition; default;
Parameters
Index
Holds an index in the range 0..Count - 1.

Remarks
Use the Items property to iterate through all conditions. Index identifies the index in the range
0..Count - 1. Items can reference a particular condition by its index, but the Condition property
is preferred in order to avoid depending on the order of the conditions.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.2.4 Text Property

The property returns condition names and values as CONDITION_NAME=CONDITIONClass
TDAConditions

Syntaxproperty Text: string;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.2.5 WhereSQL Property

Returns the SQL WHERE condition added in the Conditions property.

Class© 2019 DevartReference421

TDAConditions

Syntaxproperty WhereSQL: string;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.3 Methods

Methods of the TDAConditions class.
For a complete list of the TDAConditions class members, see the TDAConditions Members
topic.

PublicName

DeleteDescription
Overloaded. Adds a
condition to the WHERE
clause of the query.
Deletes the condition

DisableDisables the condition

EnableEnables the condition

Add

Find

Get

IndexOf

RemoveSee Also© 2019 Devart

Search for TDACondition(the condition) by its name. If
found, the TDACondition
object is returned, otherwise- nil.
Retrieving a TDACondition
object by its name. If found,the TDACondition object isreturned, otherwise - anexception is raised.
Retrieving condition index by
its name. If found, thiscondition index is returned,
otherwise - the method
returns -1.
Removes the condition

422

SQL Server Data Access Components

TDAConditions Class
TDAConditions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.3.1 Add Method

Adds a condition to the WHERE clause of the query.

Class
TDAConditions

Overload List
Name
Add(const Value: string; Enabled:
Boolean)Add(const Name: string; const Value:
string; Enabled: Boolean)© 1997-2019
Request Support
Devart. All Rights
Reserved.

Description
Adds a condition to the WHERE clause of
the query.
Adds a condition to the WHERE clause of
the query.
DAC Forum

Provide Feedback

Adds a condition to the WHERE clause of the query.

Class
TDAConditions

Syntaxfunction Add(const Value: string; Enabled: Boolean = True):
TDACondition; overload;
Parameters
Value
The value of the condition
EnabledIndicates that the condition is enabled

Remarks
If you want then to access the condition, you should use Add and its name in the Name

© 2019 DevartReference423

parameter.
The given example code will return the following SQL:
SELECT * FROM EMP
WHERE (JOB="MANAGER")
and(SAL<2500)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Adds a condition to the WHERE clause of the query.

Class
TDAConditions

Syntaxfunction Add(const Name: string; const Value: string; Enabled:
Boolean = True): TDACondition; overload;
Parameters
Name
Sets the name of the condition
Value
The value of the condition
EnabledIndicates that the condition is enabled

Remarks
The given example code will return the following SQL:
SELECT * FROM EMP
WHERE (JOB="MANAGER")
and(SAL<2500)© 1997-2019
Devart. All Rights
Reserved.
5.10.1.9.3.2 Delete Method

Deletes the condition

Class
TDAConditions© 2019 Devart

Request Support

DAC Forum

Provide Feedback

424

SQL Server Data Access Components

Syntax
procedure Delete(Index: integer);
Parameters
Index
Index of the condition© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.10.1.9.3.3 Disable Method

Disables the condition

Class
TDAConditions

Syntax
procedure Disable;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.9.3.4 Enable Method

Enables the condition

Class
TDAConditions

Syntax
procedure Enable;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.9.3.5 Find Method

Search for TDACondition (the condition) by its name. If found, the TDACondition object isreturned, otherwise - nil.

Class
© 2019 DevartReference

425

TDAConditions

Syntaxfunction Find(const Name: string): TDACondition;
ParametersName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.3.6 Get Method

Retrieving a TDACondition object by its name. If found, the TDACondition object is returned,
otherwise - an exception is raised.

Class
TDAConditions

Syntaxfunction Get(const Name: string): TDACondition;
ParametersName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.9.3.7 IndexOf Method

Retrieving condition index by its name. If found, this condition index is returned, otherwise the method returns -1.

Class
TDAConditions

Syntaxfunction IndexOf(const Name: string): Integer;
ParametersName© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

426

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.10.1.9.3.8 Remove Method

Removes the condition

Class
TDAConditions

Syntax
procedure Remove(const Name: string);
Parameters
Name
Specifies the name of the removed condition© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10 TDAConnectionOptions ClassThis class allows setting up the behaviour of the TDAConnection class.
For a list of all members of this type, see TDAConnectionOptions members.

Unit
DBAccess

SyntaxTDAConnectionOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.1 Members

TDAConnectionOptions class overview.

Properties
Name

Description

AllowImplicitConnect

Specifies whether to allow or
not implicit connection© 2019 DevartReference

opening.
Used to determine thedefault type of local sortingfor string fields. It is used
when a sort type is not
specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa
mes property of a dataset.
Used to open a connection
only when needed for
performing a server call andcloses after performing theoperation.
Used to prevent anapplication from establishinga connection at the time ofstartup.
If True, theTCustomDAConnection.On
ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.

DefaultSortType

DisconnectedMode

KeepDesignConnected

LocalFailover© 1997-2019
Devart. All Rights
Reserved.

Request Support

427

DAC Forum

Provide Feedback

5.10.1.10.2 Properties

Properties of the TDAConnectionOptions class.
For a complete list of the TDAConnectionOptions class members, see the
TDAConnectionOptions Members topic.

PublicName

Description

DefaultSortType

Used to determine thedefault type of local sortingfor string fields. It is used
when a sort type is not
specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa© 2019 Devart

428

SQL Server Data Access Components

mes property of a dataset.
Used to open a connection
only when needed for
performing a server call andcloses after performing theoperation.
Used to prevent anapplication from establishinga connection at the time ofstartup.
If True, theTCustomDAConnection.On
ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.

DisconnectedMode

KeepDesignConnected

LocalFailover

Published
Name

Description
Specifies whether to allow or
not implicit connection
opening.

AllowImplicitConnect

See Also
TDAConnectionOptions Class
TDAConnectionOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.2.1 Allow ImplicitConnect Property

Specifies whether to allow or not implicit connection opening.

Class
TDAConnectionOptions

Syntaxproperty AllowImplicitConnect: boolean default True;

Remarks© 2019 DevartReference429

Use the AllowImplicitConnect property to specify whether allow or not implicit connection
opening.
If a closed connection has AllowImplicitConnect set to True and a dataset that uses theconnection is opened, the connection is opened implicitly to allow opening the dataset.
If a closed connection has AllowImplicitConnect set to False and a dataset that uses theconnection is opened, an exception is raised.
The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.2.2 DefaultSortType Property

Used to determine the default type of local sorting for string fields. It is used when a sort type
is not specified explicitly after the field name in the TMemDataSet.IndexFieldNames property
of a dataset.

Class
TDAConnectionOptions

Syntaxproperty DefaultSortType: TSortType default stCaseSensitive;

Remarks
Use the DefaultSortType property to determine the default type of local sorting for string fields.
It is used when a sort type is not specified explicitly after the field name in the
TMemDataSet.IndexFieldNames property of a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.2.3 DisconnectedMode Property

Used to open a connection only when needed for performing a server call and closes after
performing the operation.

Class
TDAConnectionOptions

Syntax© 2019 Devart

430

SQL Server Data Access Components

property DisconnectedMode: boolean default False;

Remarks
If True, connection opens only when needed for performing a server call and closes after
performing the operation. Datasets remain opened when connection closes. May be useful tosave server resources and operate in unstable or expensive network. Drawback of using
disconnect mode is that each connection establishing requires some time for authorization. If
connection is often closed and opened it can slow down the application work. See theDisconnected Mode topic for more information.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.2.4 KeepDesignConnected Property

Used to prevent an application from establishing a connection at the time of startup.

Class
TDAConnectionOptions

Syntaxproperty KeepDesignConnected: boolean default True;

Remarks
At the time of startup prevents application from establishing a connection even if theConnected property was set to True at design-time. Set KeepDesignConnected to False toinitialize the connected property to False, even if it was True at design-time.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.10.2.5 LocalFailover Property

If True, the TCustomDAConnection.OnConnectionLost event occurs and a failover operation
can be performed after connection breaks.

Class
TDAConnectionOptions

Syntax© 2019 DevartReference431

property LocalFailover: boolean default False;

Remarks
If True, the TCustomDAConnection.OnConnectionLost event occurs and a failover operation
can be performed after connection breaks. Read the Working in an Unstable Network topic formore information about using failover.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11 TDADataSetOptions ClassThis class allows setting up the behaviour of the TDADataSet class.
For a list of all members of this type, see TDADataSetOptions members.

Unit
DBAccess

SyntaxTDADataSetOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.1 Members

TDADataSetOptions class overview.

Properties
Name
AutoPrepare

CacheCalcFields

CompressBlobMode

DefaultValues© 2019 Devart

Description
Used to execute automatic
TCustomDADataSet.Prepar
e on the query execution.
Used to enable caching of
the TField.Calculated and
TField.Lookup fields.
Used to store values of the
BLOB fields in compressed
form.
Used to request default
values/expressions from theserver and assign them to432

SQL Server Data Access Components

DetailDelay

FieldsOrigin

FlatBuffers

InsertAllSetFields

LocalMasterDetail

LongStrings

MasterFieldsNullable

NumberRange

QueryRecCountthe DefaultExpression
property.
Used to get or set a delay inmilliseconds before
refreshing detail dataset
while navigating masterdataset.
Used forTCustomDADataSet to fill
the Origin property of the
TField objects byappropriate value when
opening a dataset.
Used to control how adataset treats data of theftString and ftVarBytes
fields.
Used to include all set
dataset fields in thegenerated INSERT
statement
Used forTCustomDADataSet to use
local filtering to establish
master/detail relationship for
detail dataset and does notrefer to the server.
Used to represent string
fields with the length that isgreater than 255 as
TStringField.
Allows to use NULL values
in the fields by which therelation is built, whengenerating the query for the
Detail tables (when thisoption is enabled, theperformance can get worse).
Used to set the MaxValueand MinValue properties of
TIntegerField and
TFloatField to appropriate
values.
Used forTCustomDADataSet to© 2019 DevartReference

QuoteNames

RemoveOnRefresh

RequiredFields

ReturnParams

SetFieldsReadOnly

StrictUpdate

TrimFixedChar

UpdateAllFields

UpdateBatchSize© 2019 Devart

433

perform additional query to
get the record count for thisSELECT, so the
RecordCount property
reflects the actual number ofrecords.
Used forTCustomDADataSet toquote all database object
names in autogenerated
SQL statements such as
update SQL.
Used for a dataset to locallyremove a record that can not
be found on the server.
Used forTCustomDADataSet to set
the Required property of the
TField objects for the NOTNULL fields.
Used to return the new valueof fields to dataset after
insert or update.
Used for a dataset to set the
ReadOnly property to True
for all fields that do notbelong to UpdatingTable or
can not be updated.
Used forTCustomDADataSet toraise an exception when thenumber of updated ordeleted records is not equal
1.
Specifies whether to discard
all trailing spaces in thestring fields of a dataset.
Used to include all dataset
fields in the generated
UPDATE and INSERT
statements.
Used to get or set a valuethat enables or disables
batch processing support,
and specifies the number of434

SQL Server Data Access Components

commands that can be
executed in a batch.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2 Properties

Properties of the TDADataSetOptions class.
For a complete list of the TDADataSetOptions class members, see the TDADataSetOptions
Members topic.

PublicName
AutoPrepare

CacheCalcFields

CompressBlobMode

DefaultValues

DetailDelay

FieldsOrigin

FlatBuffers

Description
Used to execute automatic
TCustomDADataSet.Prepar
e on the query execution.
Used to enable caching of
the TField.Calculated and
TField.Lookup fields.
Used to store values of the
BLOB fields in compressed
form.
Used to request default
values/expressions from theserver and assign them tothe DefaultExpression
property.
Used to get or set a delay inmilliseconds before
refreshing detail dataset
while navigating masterdataset.
Used forTCustomDADataSet to fill
the Origin property of the
TField objects byappropriate value when
opening a dataset.
Used to control how adataset treats data of theftString and ftVarBytes
fields.
© 2019 DevartReference

InsertAllSetFields

LocalMasterDetail

LongStrings

MasterFieldsNullable

NumberRange

QueryRecCount

QuoteNames

RemoveOnRefresh
RequiredFields© 2019 Devart

435

Used to include all set
dataset fields in thegenerated INSERT
statement
Used forTCustomDADataSet to use
local filtering to establish
master/detail relationship for
detail dataset and does notrefer to the server.
Used to represent string
fields with the length that isgreater than 255 as
TStringField.
Allows to use NULL values
in the fields by which therelation is built, whengenerating the query for the
Detail tables (when thisoption is enabled, theperformance can get worse).
Used to set the MaxValueand MinValue properties of
TIntegerField and
TFloatField to appropriate
values.
Used forTCustomDADataSet toperform additional query to
get the record count for thisSELECT, so the
RecordCount property
reflects the actual number ofrecords.
Used forTCustomDADataSet toquote all database object
names in autogenerated
SQL statements such as
update SQL.
Used for a dataset to locallyremove a record that can not
be found on the server.
Used forTCustomDADataSet to set

436

SQL Server Data Access Components

the Required property of the
TField objects for the NOTNULL fields.
Used to return the new valueof fields to dataset after
insert or update.
Used for a dataset to set the
ReadOnly property to True
for all fields that do notbelong to UpdatingTable or
can not be updated.
Used forTCustomDADataSet toraise an exception when thenumber of updated ordeleted records is not equal
1.
Specifies whether to discard
all trailing spaces in thestring fields of a dataset.
Used to include all dataset
fields in the generated
UPDATE and INSERT
statements.
Used to get or set a valuethat enables or disables
batch processing support,
and specifies the number ofcommands that can be
executed in a batch.

ReturnParams

SetFieldsReadOnly

StrictUpdate

TrimFixedChar

UpdateAllFields

UpdateBatchSize

See Also
TDADataSetOptions ClassTDADataSetOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.1 AutoPrepare Property

Used to execute automatic TCustomDADataSet.Prepare on the query execution.

Class
TDADataSetOptions© 2019 DevartReference

437

Syntaxproperty AutoPrepare: boolean default False;

Remarks
Use the AutoPrepare property to execute automatic TCustomDADataSet.Prepare on thequery execution. Makes sense for cases when a query will be executed several times, forexample, in Master/Detail relationships.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.2 CacheCalcFields Property

Used to enable caching of the TField.Calculated and TField.Lookup fields.

Class
TDADataSetOptions

Syntaxproperty CacheCalcFields: boolean default False;

Remarks
Use the CacheCalcFields property to enable caching of the TField.Calculated and
TField.Lookup fields. It can be useful for reducing CPU usage for calculated fields. Using
caching of calculated and lookup fields increases memory usage on the client side.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.3 CompressBlobMode Property

Used to store values of the BLOB fields in compressed form.

Class
TDADataSetOptions

Syntaxproperty CompressBlobMode: TCompressBlobMode default cbNone;© 2019 Devart

438

SQL Server Data Access Components

Remarks
Use the CompressBlobMode property to store values of the BLOB fields in compressed form.
Add the MemData unit to uses list to use this option. Compression rate greatly depends onstored data, for example, usually graphic data compresses badly unlike text.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.4 DefaultValues Property

Used to request default values/expressions from the server and assign them to theDefaultExpression property.

Class
TDADataSetOptions

Syntaxproperty DefaultValues: boolean default False;

Remarks
If True, the default values/expressions are requested from the server and assigned to theDefaultExpression property of TField objects replacing already existent values.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.5 DetailDelay Property

Used to get or set a delay in milliseconds before refreshing detail dataset while navigating
master dataset.

Class
TDADataSetOptions

Syntaxproperty DetailDelay: integer default 0;

Remarks
Use the DetailDelay property to get or set a delay in milliseconds before refreshing detail© 2019 DevartReference439

dataset while navigating master dataset. If DetailDelay is 0 (the default value) then refreshingof detail dataset occurs immediately. The DetailDelay option should be used for detail dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.6 FieldsOrigin Property

Used for TCustomDADataSet to fill the Origin property of the TField objects by appropriate
value when opening a dataset.

Class
TDADataSetOptions

Syntaxproperty FieldsOrigin: boolean;

Remarks
If True, TCustomDADataSet fills the Origin property of the TField objects by appropriate value
when opening a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.7 FlatBuffers Property

Used to control how a dataset treats data of the ftString and ftVarBytes fields.

Class
TDADataSetOptions

Syntaxproperty FlatBuffers: boolean default False;

Remarks
Use the FlatBuffers property to control how a dataset treats data of the ftString and ftVarBytes
fields. When set to True, all data fetched from the server is stored in record pdata without
unused tails.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

440

SQL Server Data Access Components

Reserved.
5.10.1.11.2.8 InsertAllSetFields Property

Used to include all set dataset fields in the generated INSERT statement

Class
TDADataSetOptions

Syntaxproperty InsertAllSetFields: boolean default False;

Remarks
If True, all set dataset fields, including those set to NULL explicitly, will be included in thegenerated INSERT statements. Otherwise, only set fields containing not NULL values will be
included to the generated INSERT statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.9 LocalMasterDetail Property

Used for TCustomDADataSet to use local filtering to establish master/detail relationship for
detail dataset and does not refer to the server.

Class
TDADataSetOptions

Syntaxproperty LocalMasterDetail: boolean default False;

Remarks
If True, for detail dataset in master-detail relationship TCustomDADataSet uses local filtering
for establishing master/detail relationship and does not refer to the server. Otherwise detaildataset performs query each time a record is selected in master dataset. This option is usefulfor reducing server calls number, server resources economy. It can be useful for slow
connection. The TMemDataSet.CachedUpdates mode can be used for detail dataset only
when this option is set to true. Setting the LocalMasterDetail option to True is notrecommended when detail table contains too many rows, because when it is set to False,
only records that correspond to the current record in master dataset are fetched.

© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

441

Provide Feedback

5.10.1.11.2.10 LongStrings Property

Used to represent string fields with the length that is greater than 255 as TStringField.

Class
TDADataSetOptions

Syntaxproperty LongStrings: boolean default True;

Remarks
Use the LongStrings property to represent string fields with the length that is greater than 255
as TStringField, not as TMemoField.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.11 MasterFieldsNullable Property

Allows to use NULL values in the fields by which the relation is built, when generating thequery for the Detail tables (when this option is enabled, the performance can get worse).

Class
TDADataSetOptions

Syntaxproperty MasterFieldsNullable: boolean default False;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.12 NumberRange Property

Used to set the MaxValue and MinValue properties of TIntegerField and TFloatField toappropriate values.

Class
TDADataSetOptions© 2019 Devart

442

SQL Server Data Access Components

Syntaxproperty NumberRange: boolean default False;

Remarks
Use the NumberRange property to set the MaxValue and MinValue properties of TIntegerField
and TFloatField to appropriate values.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.13 QueryRecCount Property

Used for TCustomDADataSet to perform additional query to get the record count for thisSELECT, so the RecordCount property reflects the actual number of records.

Class
TDADataSetOptions

Syntaxproperty QueryRecCount: boolean default False;

Remarks
If True, and the FetchAll property is False, TCustomDADataSet performs additional query to
get the record count for this SELECT, so the RecordCount property reflects the actual
number of records. Does not have any effect if the FetchAll property is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.14 QuoteNames Property

Used for TCustomDADataSet to quote all database object names in autogenerated SQL
statements such as update SQL.

Class
TDADataSetOptions

Syntaxproperty QuoteNames: boolean default False;© 2019 DevartReference

443

Remarks
If True, TCustomDADataSet quotes all database object names in autogenerated SQL
statements such as update SQL.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.15 RemoveOnRefresh Property

Used for a dataset to locally remove a record that can not be found on the server.

Class
TDADataSetOptions

Syntaxproperty RemoveOnRefresh: boolean default True;

Remarks
When the RefreshRecord procedure can't find necessary record on the server andRemoveOnRefresh is set to True, dataset removes the record locally. Usually
RefreshRecord can't find necessary record when someone else dropped the record orchanged the key value of it.
This option makes sense only if the StrictUpdate option is set to False. If the StrictUpdate
option is True, error will be generated regardless of the RemoveOnRefresh option value.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.16 RequiredFields Property

Used for TCustomDADataSet to set the Required property of the TField objects for the NOTNULL fields.

Class
TDADataSetOptions

Syntaxproperty RequiredFields: boolean default True;

Remarks© 2019 Devart

444

SQL Server Data Access Components

If True, TCustomDADataSet sets the Required property of the TField objects for the NOTNULL fields. It is useful when table has a trigger which updates the NOT NULL fields.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.17 ReturnParams Property

Used to return the new value of fields to dataset after insert or update.

Class
TDADataSetOptions

Syntaxproperty ReturnParams: boolean default False;

Remarks
Use the ReturnParams property to return the new value of fields to dataset after insert or
update. The actual value of field after insert or update may be different from the value stored
in the local memory if the table has a trigger. When ReturnParams is True, OUT parametersof the SQLInsert and SQLUpdate statements is assigned to the corresponding fields.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.18 SetFieldsReadOnly Property

Used for a dataset to set the ReadOnly property to True for all fields that do not belong toUpdatingTable or can not be updated.

Class
TDADataSetOptions

Syntaxproperty SetFieldsReadOnly: boolean default True;

Remarks
If True, dataset sets the ReadOnly property to True for all fields that do not belong toUpdatingTable or can not be updated. Set this option for datasets that use automatic
generation of the update SQL statements only.

© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

445

Provide Feedback

5.10.1.11.2.19 StrictUpdate Property

Used for TCustomDADataSet to raise an exception when the number of updated or deleted
records is not equal 1.

Class
TDADataSetOptions

Syntaxproperty StrictUpdate: boolean default True;

Remarks
If True, TCustomDADataSet raises an exception when the number of updated or deleted
records is not equal 1. Setting this option also causes the exception if the RefreshRecord
procedure returns more than one record. The exception does not occur when you execute
SQL query, that doesn't return resultset.
Note: There can be problems if this option is set to True and triggers for UPDATE, DELETE,
REFRESH commands that are defined for the table. So it is recommended to disable (set to
False) this option with triggers.
TrimFixedChar specifies whether to discard all trailing spaces in the string fields of a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.20 TrimFixedChar Property

Specifies whether to discard all trailing spaces in the string fields of a dataset.

Class
TDADataSetOptions

Syntaxproperty TrimFixedChar: boolean default True;

Remarks
Specifies whether to discard all trailing spaces in the string fields of a dataset.

© 2019 Devart

446

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.21 UpdateAllFields Property

Used to include all dataset fields in the generated UPDATE and INSERT statements.

Class
TDADataSetOptions

Syntaxproperty UpdateAllFields: boolean default False;

Remarks
If True, all dataset fields will be included in the generated UPDATE and INSERT statements.
Unspecified fields will have NULL value in the INSERT statements. Otherwise, only updated
fields will be included to the generated update statements.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.11.2.22 UpdateBatchSize Property

Used to get or set a value that enables or disables batch processing support, and specifies
the number of commands that can be executed in a batch.

Class
TDADataSetOptions

Syntaxproperty UpdateBatchSize: Integer default 1;

Remarks
Use the UpdateBatchSize property to get or set a value that enables or disables batchprocessing support, and specifies the number of commands that can be executed in a batch.
Takes effect only when updating dataset in the TMemDataSet.CachedUpdates mode. The
default value is 1.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference447

5.10.1.12 TDAEncryption Class

Used to specify the options of the data encryption in a dataset.
For a list of all members of this type, see TDAEncryption members.

Unit
DBAccess

SyntaxTDAEncryption = class(TPersistent);

Remarks
Set the properties of Encryption to specify the options of the data encryption in a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.12.1 Members

TDAEncryption class overview.

Properties
Name

Description
Used to specify theencryptor class that will
perform the data encryption.
Used to set field names forwhich encryption will be
performed.

Encryptor

Fields© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.12.2 Properties

Properties of the TDAEncryption class.
For a complete list of the TDAEncryption class members, see the TDAEncryption Members
topic.

PublicName© 2019 Devart

Description

448

SQL Server Data Access Components

Used to specify theencryptor class that will
perform the data encryption.

Encryptor

Published
Name

Description
Used to set field names forwhich encryption will be
performed.

FieldsSee Also
TDAEncryption Class
TDAEncryption Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.12.2.1 Encryptor Property

Used to specify the encryptor class that will perform the data encryption.

Class
TDAEncryption

Syntaxproperty Encryptor: TCREncryptor;

Remarks
Use the Encryptor property to specify the encryptor class that will perform the dataencryption.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.12.2.2 Fields Property

Used to set field names for which encryption will be performed.

Class
TDAEncryption© 2019 DevartReference

449

Syntaxproperty Fields: string;

Remarks
Used to set field names for which encryption will be performed. Field names must be
separated by semicolons.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13 TDAMapRule ClassClass that formes rules for Data Type Mapping.
For a list of all members of this type, see TDAMapRule members.

Unit
DBAccess

Syntax
TDAMapRule = class(TMapRule);

Remarks
Using properties of this class, it is possible to change parameter values of the specified rules
from the TDAMapRules set.

Inheritance Hierarchy
TMapRule
TDAMapRule© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.1 Members

TDAMapRule class overview.

Properties
Name© 2019 Devart

Description

450

SQL Server Data Access Components

Maximum DB field length,
until which the rule isapplied.
Minimum DB field length,
starting from which the rule
is applied.
Maximum DB field scale,until which the rule is applied
to the specified DB field.
Minimum DB field Scale,starting from which the rule
is applied to the specified
DB field.
DB field type, that the rule isapplied to.
The resultant field length inDelphi.
DataSet field name, forwhich the rule is applied.
The resultant field Scale in
Delphi.
Delphi field type, that the
specified DB type or
DataSet field will bemapped to.
Ignoring errors whenconverting data from DB toDelphi type.

DBLengthMax

DBLengthMin

DBScaleMax

DBScaleMin

DBTypeFieldLength
FieldName
FieldScale

FieldTypeIgnoreErrors© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2 Properties

Properties of the TDAMapRule class.
For a complete list of the TDAMapRule class members, see the TDAMapRule Members
topic.

PublishedName
DBLengthMax

Description
Maximum DB field length,
until which the rule isapplied.
© 2019 DevartReference

451

Minimum DB field length,
starting from which the rule
is applied.
Maximum DB field scale,until which the rule is applied
to the specified DB field.
Minimum DB field Scale,starting from which the rule
is applied to the specified
DB field.
DB field type, that the rule isapplied to.
The resultant field length inDelphi.
DataSet field name, forwhich the rule is applied.
The resultant field Scale in
Delphi.
Delphi field type, that the
specified DB type or
DataSet field will bemapped to.
Ignoring errors whenconverting data from DB toDelphi type.

DBLengthMin

DBScaleMax

DBScaleMin

DBTypeFieldLength
FieldName
FieldScale

FieldTypeIgnoreErrors

See Also
TDAMapRule Class
TDAMapRule Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.13.2.1 DBLengthMax Property

Maximum DB field length, until which the rule is applied.

Class
TDAMapRule

Syntaxproperty DBLengthMax: Integer default rlAny;© 2019 Devart

Provide Feedback

452

SQL Server Data Access Components

Remarks
Setting maximum DB field length, until which the rule is applied to the specified DB field.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.2 DBLengthMin Property

Minimum DB field length, starting from which the rule is applied.

Class
TDAMapRule

Syntaxproperty DBLengthMin: Integer default rlAny;

Remarks
Setting minimum DB field length, starting from which the rule is applied to the specified DB
field.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.3 DBScaleMax Property

Maximum DB field scale, until which the rule is applied to the specified DB field.

Class
TDAMapRule

Syntaxproperty DBScaleMax: Integer default rlAny;

Remarks
Setting maximum DB field scale, until which the rule is applied to the specified DB field.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference453

5.10.1.13.2.4 DBScaleMin Property

Minimum DB field Scale, starting from which the rule is applied to the specified DB field.

Class
TDAMapRule

Syntaxproperty DBScaleMin: Integer default rlAny;

Remarks
Setting minimum DB field Scale, starting from which the rule is applied to the specified DB
field.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.5 DBType Property

DB field type, that the rule is applied to.

Class
TDAMapRule

Syntaxproperty DBType: Word default dtUnknown;

Remarks
Setting DB field type, that the rule is applied to. If the current rule is set for Connection, therule will be applied to all fields of the specified type in all DataSets related to this Connection.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.13.2.6 FieldLength Property

The resultant field length in Delphi.

Class
TDAMapRule© 2019 Devart

DAC Forum

Provide Feedback

454

SQL Server Data Access Components

Syntaxproperty FieldLength: Integer default rlAny;

Remarks
Setting the Delphi field length after conversion.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.7 FieldName Property

DataSet field name, for which the rule is applied.

Class
TDAMapRule

Syntaxproperty FieldName: string;

Remarks
Specifies the DataSet field name, that the rule is applied to. If the current rule is set forConnection, the rule will be applied to all fields with such name in DataSets related to thisConnection.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.8 FieldScale Property

The resultant field Scale in Delphi.

Class
TDAMapRule

Syntaxproperty FieldScale: Integer default rlAny;

Remarks
Setting the Delphi field Scale after conversion.

© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

455

Provide Feedback

5.10.1.13.2.9 FieldType Property

Delphi field type, that the specified DB type or DataSet field will be mapped to.

Class
TDAMapRule

Syntaxproperty FieldType: TFieldType stored IsFieldTypeStored default
ftUnknown;

Remarks
Setting Delphi field type, that the specified DB type or DataSet field will be mapped to.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.13.2.10 IgnoreErrors Property

Ignoring errors when converting data from DB to Delphi type.

Class
TDAMapRule

Syntaxproperty IgnoreErrors: Boolean default False;

Remarks
Allows to ignore errors while data conversion in case if data or DB data format cannot berecorded to the specified Delphi field type. The default value is false.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.14 TDAMapRules Class

Used for adding rules for DataSet fields mapping with both identifying by field name and by
field type and Delphi field types.

© 2019 Devart

456

SQL Server Data Access Components

For a list of all members of this type, see TDAMapRules members.

Unit
DBAccess

Syntax
TDAMapRules = class(TMapRules);Inheritance Hierarchy
TMapRules
TDAMapRules© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.14.1 Members

TDAMapRules class overview.

Properties
Name

Description
Used to avoid raising
exception on mapping rulesthat can't be applied.

IgnoreInvalidRules© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.14.2 Properties

Properties of the TDAMapRules class.
For a complete list of the TDAMapRules class members, see the TDAMapRules Members
topic.

Published
Name
IgnoreInvalidRules

Description
Used to avoid raising
exception on mapping rulesthat can't be applied.

© 2019 DevartReference

457

See Also
TDAMapRules Class
TDAMapRules Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.14.2.1 IgnoreInvalidRules Property

Used to avoid raising exception on mapping rules that can't be applied.

Class
TDAMapRules

Syntaxproperty IgnoreInvalidRules: boolean default False;

Remarks
Allows to ignore errors (not to raise exception) during data conversion in case if the data or
DB data format cannot be recorded to the specified Delphi field type. The default value isfalse.
Note: In order to ignore errors occurring during data conversion, use the
TDAMapRule.IgnoreErrors property

See Also
TDAMapRule.IgnoreErrors© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15 TDAMetaData ClassA class for retrieving metainformation of the specified database objects in the form of dataset.
For a list of all members of this type, see TDAMetaData members.

Unit
DBAccess

Syntax© 2019 Devart

458

SQL Server Data Access Components

TDAMetaData = class(TMemDataSet);

Remarks
TDAMetaData is a TDataSet descendant standing for retrieving metainformation of thespecified database objects in the form of dataset. First of all you need to specify which kind ofmetainformation you want to see. For this you need to assign the
TDAMetaData.MetaDataKind property. Provide one or more conditions in the
TDAMetaData.Restrictions property to diminish the size of the resultset and get only
information you are interested in.
Use the TDAMetaData.GetMetaDataKinds method to get the full list of supported kinds ofmeta data. With the TDAMetaData.GetRestrictions method you can find out what restrictions
are applicable to the specified MetaDataKind.

ExampleThe code below demonstrates how to get information about columns of the 'emp' table:
MetaData.Connection := Connection;
MetaData.MetaDataKind := 'Columns';
MetaData.Restrictions.Values['TABLE_NAME'] := 'Emp';
MetaData.Open;Inheritance Hierarchy
TMemDataSet
TDAMetaData

See Also
TDAMetaData.MetaDataKind
TDAMetaData.Restrictions
TDAMetaData.GetMetaDataKinds
TDAMetaData.GetRestrictions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.1 Members

TDAMetaData class overview.

Properties
Name

Description© 2019 DevartReference

CachedUpdates (inherited from TMemDataSet)

Connection
IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)
MetaDataKind
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
Restrictions

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

459

Used to enable or disable
the use of cached updates
for a dataset.
Used to specify aconnection object to use toconnect to a data store.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to specify which kindof metainformation to show.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to provide one or moreconditions restricting the listof objects to be described.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)© 2019 Devart

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cached460

SQL Server Data Access Components

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

GetMetaDataKinds

GetRestrictions

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

updates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Used to get values
acceptable in the
MetaDataKind property.
Used to find out which
restrictions are applicable toa certain MetaDataKind.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
© 2019 DevartReference

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

461

Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.

OnUpdateRecord (inherited from TMemDataSet)

Occurs when a single© 2019 Devart

462

SQL Server Data Access Components

update component can nothandle the updates.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.2 Properties

Properties of the TDAMetaData class.
For a complete list of the TDAMetaData class members, see the TDAMetaData Members
topic.

PublicName
CachedUpdates (inherited from TMemDataSet)

Connection
IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)
MetaDataKind
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
Restrictions

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to specify aconnection object to use toconnect to a data store.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to specify which kindof metainformation to show.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to provide one or moreconditions restricting the list
© 2019 DevartReference

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)463

of objects to be described.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

See Also
TDAMetaData Class
TDAMetaData Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.2.1 Connection Property

Used to specify a connection object to use to connect to a data store.

Class
TDAMetaData

Syntaxproperty Connection: TCustomDAConnection;

Remarks
Use the Connection property to specify a connection object to use to connect to a data store.
Set at design-time by selecting from the list of provided TCustomDAConnection or its
descendant class objects.
At runtime, set the Connection property to reference an instanciated TCustomDAConnection
object.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.15.2.2 MetaDataKind Property

Used to specify which kind of metainformation to show.

Class
TDAMetaData© 2019 Devart

Provide Feedback

464

SQL Server Data Access Components

Syntaxproperty MetaDataKind: string;

Remarks
This string property specifies which kind of metainformation to show. The value of thisproperty should be assigned before activating the component. If MetaDataKind equals to an
empty string (the default value), the full value list that this property accepts will be shown.
They are described in the table below:

MetaDataKind
Columns
Constraints
IndexColumns
Indexes

Description
show metainformation about columns of existing tables
show metainformation about the constraints defined in the databaseshow metainformation about indexed columns
show metainformation about indexes in a databaseshow the acceptable values of this property. You will get the same
MetaDataKinds
result if the MetadataKind property is an empty string
ProcedureParashow metainformation about parameters of existing procedures
metersProceduresshow metainformation about existing procedures
generates a dataset that describes which restrictions are applicable
Restrictions
to each MetaDataKind
Tablesshow metainformation about existing tables
Databases
show metainformation about existing databases
If you provide a value that equals neither of the values described in the table, an error will beraised.

See Also
Restrictions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.2.3 Restrictions Property

Used to provide one or more conditions restricting the list of objects to be described.

Class
TDAMetaData© 2019 DevartReference

465

Syntaxproperty Restrictions: TStrings;

Remarks
Use the Restriction list to provide one or more conditions restricting the list of objects to be
described. To see the full list of restrictions and to which metadata kinds they are applicable,
you should assign the Restrictions value to the MetaDataKind property and view the result.

See Also
MetaDataKind© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.3 Methods

Methods of the TDAMetaData class.
For a complete list of the TDAMetaData class members, see the TDAMetaData Members
topic.

PublicName
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)© 2019 Devart

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.

466

SQL Server Data Access Components

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

GetMetaDataKinds

GetRestrictions

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Used to get values
acceptable in the
MetaDataKind property.
Used to find out which
restrictions are applicable toa certain MetaDataKind.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in the© 2019 DevartReference

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

467

dataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TDAMetaData Class
TDAMetaData Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.15.3.1 GetMetaDataKinds Method

Used to get values acceptable in the MetaDataKind property.

Class
TDAMetaData

Syntax
procedure GetMetaDataKinds(List: TStrings);
Parameters
List
Holds the object that will be filled with metadata kinds (restrictions).

Remarks© 2019 Devart

Provide Feedback

468

SQL Server Data Access Components

Call the GetMetaDataKinds method to get values acceptable in the MetaDataKind property.
The List parameter will be cleared and then filled with values.

See Also
MetaDataKind© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.15.3.2 GetRestrictions Method

Used to find out which restrictions are applicable to a certain MetaDataKind.

Class
TDAMetaData

Syntax
procedure GetRestrictions(List: TStrings; const MetaDataKind:
string);Parameters
List
Holds the object that will be filled with metadata kinds (restrictions).
MetaDataKind
Holds the metadata kind for which restrictions are returned.

Remarks
Call the GetRestrictions method to find out which restrictions are applicable to a certain
MetaDataKind. The List parameter will be cleared and then filled with values.

See Also
Restrictions
GetMetaDataKinds© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16 TDAParam ClassA class that forms objects to represent the values of the parameters set.
For a list of all members of this type, see TDAParam members.

© 2019 DevartReference

469

Unit
DBAccess

SyntaxTDAParam = class(TParam);

Remarks
Use the properties of TDAParam to set the value of a parameter. Objects that use
parameters create TDAParam objects to represent these parameters. For example,
TDAParam objects are used by TCustomDASQL, TCustomDADataSet.
TDAParam shares many properties with TField, as both describe the value of a field in adataset. However, a TField object has several properties to describe the field binding and theway the field is displayed, edited, or calculated, that are not needed in a TDAParam object.
Conversely, TDAParam includes properties that indicate how the field value is passed as aparameter.

See Also
TCustomDADataSet
TCustomDASQL
TDAParams© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.1 Members

TDAParam class overview.

Properties
Name
AsBlobAsBlobRef

AsFloat© 2019 Devart

Description
Used to set and read thevalue of the BLOB
parameter as string.
Used to set and read thevalue of the BLOB
parameter as a TBlob
object.
Used to assign the value fora float field to a parameter.

470

SQL Server Data Access Components

AsInteger

AsLargeInt

AsMemoAsMemoRef

AsSQLTimeStamp

AsString
AsWideString
DataType
IsNullParamType
Size
Value

Used to assign the value for
an integer field to theparameter.
Used to assign the value fora LargeInteger field to theparameter.
Used to assign the value fora memo field to theparameter.
Used to set and read thevalue of the memo
parameter as a TBlob
object.
Used to specify the value ofthe parameter when it
represents a SQL
timestamp field.
Used to assign the stringvalue to the parameter.
Used to assign the Unicode
string value to theparameter.
Indicates the data type of theparameter.
Used to indicate whether thevalue assigned to aparameter is NULL.
Used to indicate the type ofuse for a parameter.
Specifies the size of a string
type parameter.
Used to represent the valueof the parameter as Variant.

Methods
Name
AssignField
AssignFieldValue
LoadFromFile

Description
Assigns field name and fieldvalue to a param.
Assigns the specified field
properties and value to aparameter.
Places the content of a
specified file into a© 2019 DevartReference

TDAParam object.
Places the content from astream into a TDAParamobject.
Overloaded. Writes the datafrom a specified buffer to
BLOB.

LoadFromStream

SetBlobData© 1997-2019
Devart. All Rights
Reserved.

471

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2 Properties

Properties of the TDAParam class.
For a complete list of the TDAParam class members, see the TDAParam Members topic.

PublicName
AsBlobAsBlobRef

AsFloat
AsInteger

AsLargeInt

AsMemoAsMemoRef

AsSQLTimeStamp© 2019 Devart

Description
Used to set and read thevalue of the BLOB
parameter as string.
Used to set and read thevalue of the BLOB
parameter as a TBlob
object.
Used to assign the value fora float field to a parameter.
Used to assign the value for
an integer field to theparameter.
Used to assign the value fora LargeInteger field to theparameter.
Used to assign the value fora memo field to theparameter.
Used to set and read thevalue of the memo
parameter as a TBlob
object.
Used to specify the value ofthe parameter when it
represents a SQL

472

SQL Server Data Access Components

timestamp field.
Used to assign the stringvalue to the parameter.
Used to assign the Unicode
string value to theparameter.
Used to indicate whether thevalue assigned to aparameter is NULL.

AsString
AsWideString

IsNullPublished
Name

Description
Indicates the data type of theparameter.
Used to indicate the type ofuse for a parameter.
Specifies the size of a string
type parameter.
Used to represent the valueof the parameter as Variant.

DataType
ParamType
Size
Value

See Also
TDAParam Class
TDAParam Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.1 AsBlob Property

Used to set and read the value of the BLOB parameter as string.

Class
TDAParam

Syntaxproperty AsBlob: TBlobData;

Remarks
Use the AsBlob property to set and read the value of the BLOB parameter as string. Setting© 2019 DevartReference

473

AsBlob will set the DataType property to ftBlob.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.2 AsBlobRef Property

Used to set and read the value of the BLOB parameter as a TBlob object.

Class
TDAParam

Syntaxproperty AsBlobRef: TBlob;

Remarks
Use the AsBlobRef property to set and read the value of the BLOB parameter as a TBlob
object. Setting AsBlobRef will set the DataType property to ftBlob.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.3 AsFloat Property

Used to assign the value for a float field to a parameter.

Class
TDAParam

Syntaxproperty AsFloat: double;

Remarks
Use the AsFloat property to assign the value for a float field to the parameter. Setting AsFloat
will set the DataType property to dtFloat.
Read the AsFloat property to determine the value that was assigned to an output parameter,
represented as Double. The value of the parameter will be converted to the Double value if
possible.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

474

SQL Server Data Access Components

Reserved.
5.10.1.16.2.4 AsInteger Property

Used to assign the value for an integer field to the parameter.

Class
TDAParam

Syntaxproperty AsInteger: LongInt;

Remarks
Use the AsInteger property to assign the value for an integer field to the parameter. Setting
AsInteger will set the DataType property to dtInteger.
Read the AsInteger property to determine the value that was assigned to an output parameter,
represented as a 32-bit integer. The value of the parameter will be converted to the Integer
value if possible.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.5 AsLargeInt Property

Used to assign the value for a LargeInteger field to the parameter.

Class
TDAParam

Syntaxproperty AsLargeInt: Int64;

Remarks
Set the AsLargeInt property to assign the value for an Int64 field to the parameter. Setting
AsLargeInt will set the DataType property to dtLargeint.
Read the AsLargeInt property to determine the value that was assigned to an output
parameter, represented as a 64-bit integer. The value of the parameter will be converted to
the Int64 value if possible.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

475

Reserved.
5.10.1.16.2.6 AsMemo Property

Used to assign the value for a memo field to the parameter.

Class
TDAParam

Syntaxproperty AsMemo: string;

Remarks
Use the AsMemo property to assign the value for a memo field to the parameter. Setting
AsMemo will set the DataType property to ftMemo.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.7 AsMemoRef Property

Used to set and read the value of the memo parameter as a TBlob object.

Class
TDAParam

Syntaxproperty AsMemoRef: TBlob;

Remarks
Use the AsMemoRef property to set and read the value of the memo parameter as a TBlob
object. Setting AsMemoRef will set the DataType property to ftMemo.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.8 AsSQLTimeStamp Property

Used to specify the value of the parameter when it represents a SQL timestamp field.

Class© 2019 Devart

476

SQL Server Data Access Components

TDAParam

Syntaxproperty AsSQLTimeStamp: TSQLTimeStamp;

Remarks
Set the AsSQLTimeStamp property to assign the value for a SQL timestamp field to theparameter. Setting AsSQLTimeStamp sets the DataType property to ftTimeStamp.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.9 AsString Property

Used to assign the string value to the parameter.

Class
TDAParam

Syntaxproperty AsString: string;

Remarks
Use the AsString property to assign the string value to the parameter. Setting AsString will set
the DataType property to ftString.
Read the AsString property to determine the value that was assigned to an output parameter
represented as a string. The value of the parameter will be converted to a string.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.10 AsWideString Property

Used to assign the Unicode string value to the parameter.

Class
TDAParam

Syntaxproperty AsWideString: string;© 2019 DevartReference

477

Remarks
Set AsWideString to assign the Unicode string value to the parameter. Setting AsWideString
will set the DataType property to ftWideString.
Read the AsWideString property to determine the value that was assigned to an output
parameter, represented as a Unicode string. The value of the parameter will be converted to a
Unicode string.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.11 DataType Property

Indicates the data type of the parameter.

Class
TDAParam

Syntaxproperty DataType: TFieldType stored IsDataTypeStored;

Remarks
DataType is set automatically when a value is assigned to a parameter. Do not set DataTypefor bound fields, as this may cause the assigned value to be misinterpreted.
Read DataType to learn the type of data that was assigned to the parameter. Every possible
value of DataType corresponds to the type of a database field.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.16.2.12 IsNull Property

Used to indicate whether the value assigned to a parameter is NULL.

Class
TDAParam

Syntaxproperty IsNull: boolean;

Remarks© 2019 Devart

Provide Feedback

478

SQL Server Data Access Components

Use the IsNull property to indicate whether the value assigned to a parameter is NULL.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.13 ParamType Property

Used to indicate the type of use for a parameter.

Class
TDAParam

Syntaxproperty ParamType default DB . ptUnknown;

Remarks
Objects that use TDAParam objects to represent field parameters set ParamType to indicate
the type of use for a parameter.
To learn the description of TParamType refer to Delphi Help.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.2.14 Size Property

Specifies the size of a string type parameter.

Class
TDAParam

Syntaxproperty Size: integer default 0;

Remarks
Use the Size property to indicate the maximum number of characters the parameter may
contain. Use the Size property only for Output parameters of the ftString, ftFixedChar,ftBytes, ftVarBytes, or ftWideString type.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference479

5.10.1.16.2.15 Value Property

Used to represent the value of the parameter as Variant.

Class
TDAParam

Syntaxproperty Value: variant stored IsValueStored;

Remarks
The Value property represents the value of the parameter as Variant.
Use Value in generic code that manipulates the values of parameters without the need toknow the field type the parameter represent.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.3 Methods

Methods of the TDAParam class.
For a complete list of the TDAParam class members, see the TDAParam Members topic.

PublicName
AssignField
AssignFieldValue

LoadFromFile

LoadFromStream

SetBlobData

See Also© 2019 Devart

Description
Assigns field name and fieldvalue to a param.
Assigns the specified field
properties and value to aparameter.
Places the content of a
specified file into a
TDAParam object.
Places the content from astream into a TDAParamobject.
Overloaded. Writes the datafrom a specified buffer to
BLOB.

480

SQL Server Data Access Components

TDAParam Class
TDAParam Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.3.1 AssignField Method

Assigns field name and field value to a param.

Class
TDAParam

Syntax
procedure AssignField(Field: TField);Parameters
Field
Holds the field which name and value should be assigned to the param.

Remarks
Call the AssignField method to assign field name and field value to a param.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.3.2 AssignFieldValue Method

Assigns the specified field properties and value to a parameter.

Class
TDAParam

Syntax
procedure AssignFieldValue(Field: TField; const Value: Variant);
virtual;Parameters
Field
Holds the field the properties of which will be assigned to the parameter.
Value
Holds the value for the parameter.
© 2019 DevartReference

481

Remarks
Call the AssignFieldValue method to assign the specified field properties and value to aparameter.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.3.3 LoadFromFile Method

Places the content of a specified file into a TDAParam object.

Class
TDAParam

Syntax
procedure LoadFromFile(const FileName: string; BlobType:
TBlobType);
Parameters
FileName
Holds the name of the file.
BlobType
Holds a value that modifies the DataType property so that this TDAParam object now holds
the BLOB value.

Remarks
Use the LoadFromFile method to place the content of a file specified by FileName into a
TDAParam object. The BlobType value modifies the DataType property so that thisTDAParam object now holds the BLOB value.

See Also
LoadFromStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.16.3.4 LoadFromStream Method

Places the content from a stream into a TDAParam object.

Class© 2019 Devart

Provide Feedback

482

SQL Server Data Access Components

TDAParam

Syntax
procedure LoadFromStream(Stream: TStream; BlobType: TBlobType);
virtual;Parameters
StreamHolds the stream to copy content from.
BlobType
Holds a value that modifies the DataType property so that this TDAParam object now holds
the BLOB value.

Remarks
Call the LoadFromStream method to place the content from a stream into a TDAParamobject. The BlobType value modifies the DataType property so that this TDAParam object
now holds the BLOB value.

See Also
LoadFromFile© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.16.3.5 SetBlobData Method

Writes the data from a specified buffer to BLOB.

Class
TDAParam

Overload List
Name
SetBlobData(Buffer: TValueBuffer)
SetBlobData(Buffer: IntPtr; Size: Integer)© 1997-2019
Devart. All Rights
Reserved.

Request Support

Description
Writes the data from a specified buffer to
BLOB.
Writes the data from a specified buffer to
BLOB.
DAC Forum

Provide Feedback© 2019 DevartReference

483

Writes the data from a specified buffer to BLOB.

Class
TDAParam

Syntax
procedure SetBlobData(Buffer: TValueBuffer); overload;
Parameters
BufferHolds the pointer to the data.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Writes the data from a specified buffer to BLOB.

Class
TDAParam

Syntax
procedure SetBlobData(Buffer: IntPtr; Size: Integer); overload;
Parameters
BufferHolds the pointer to data.
Size
Holds the number of bytes to read from the buffer.

Remarks
Call the SetBlobData method to write data from a specified buffer to BLOB.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.17 TDAParams ClassThis class is used to manage a list of TDAParam objects for an object that uses fieldparameters.
For a list of all members of this type, see TDAParams members.

© 2019 Devart

484

SQL Server Data Access Components

Unit
DBAccess

SyntaxTDAParams = class(TParams);

Remarks
Use TDAParams to manage a list of TDAParam objects for an object that uses fieldparameters. For example, TCustomDADataSet objects and TCustomDASQL objects use
TDAParams objects to create and access their parameters.

See Also
TCustomDADataSet.Params
TCustomDASQL.Params
TDAParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.17.1 Members

TDAParams class overview.

Properties
Name

Description
Used to interate through allparameters.

Items

Methods
Name

Description
Searches for a parameterwith the specified name.
Searches for a parameterwith the specified name.

FindParam
ParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

485

5.10.1.17.2 Properties

Properties of the TDAParams class.
For a complete list of the TDAParams class members, see the TDAParams Members topic.

PublicName

Description
Used to interate through allparameters.

Items

See Also
TDAParams Class
TDAParams Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.17.2.1 Items Property(Indexer)

Used to interate through all parameters.

Class
TDAParams

Syntaxproperty Items[Index: integer]: TDAParam; default;
Parameters
Index
Holds an index in the range 0..Count - 1.

Remarks
Use the Items property to iterate through all parameters. Index identifies the index in the range
0..Count - 1. Items can reference a particular parameter by its index, but the ParamByName
method is preferred in order to avoid depending on the order of the parameters.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

486

SQL Server Data Access Components

5.10.1.17.3 Methods

Methods of the TDAParams class.
For a complete list of the TDAParams class members, see the TDAParams Members topic.

PublicName

Description
Searches for a parameterwith the specified name.
Searches for a parameterwith the specified name.

FindParam
ParamByName

See Also
TDAParams Class
TDAParams Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.17.3.1 FindParam Method

Searches for a parameter with the specified name.

Class
TDAParams

Syntaxfunction FindParam(const Value: string): TDAParam;
Parameters
Value
Holds the parameter name.
Return Valuea parameter, if a match was found. Nil otherwise.

Remarks
Use the FindParam method to find a parameter with the name passed in Value. If a match isfound, FindParam returns the parameter. Otherwise, it returns nil. Use this method rather
than a direct reference to the Items property to avoid depending on the order of the entries.
To locate more than one parameter at a time by name, use the GetParamList method© 2019 DevartReference

487

instead. To get only the value of a named parameter, use the ParamValues property.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.17.3.2 ParamByName Method

Searches for a parameter with the specified name.

Class
TDAParams

Syntaxfunction ParamByName(const Value: string): TDAParam;
Parameters
Value
Holds the parameter name.
Return Valuea parameter, if the match was found. otherwise an exception is raised.

Remarks
Use the ParamByName method to find a parameter with the name passed in Value. If amatch was found, ParamByName returns the parameter. Otherwise, an exception is raised.
Use this method rather than a direct reference to the Items property to avoid depending on theorder of the entries.
To locate a parameter by name without raising an exception if the parameter is not found, use
the FindParam method.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.18 TDATransaction ClassA base class that implements functionality for controlling transactions.
For a list of all members of this type, see TDATransaction members.

Unit
DBAccess

Syntax© 2019 Devart

Provide Feedback

488

SQL Server Data Access Components

TDATransaction = class(TComponent);

Remarks
TDATransaction is a base class for components implementing functionality for managing
transactions.
Do not create instances of TDATransaction. Use descendants of the TDATransaction classinstead.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.1 Members

TDATransaction class overview.

Properties
Name
ActiveDefaultCloseAction

Description
Used to determine if thetransaction is active.
Used to specify thetransaction behaviour when
it is destroyed while being
active, or when one of its
connections is closed withthe active transaction.

Methods
Name
CommitRollback
StartTransaction

Description
Commits the current
transaction.
Discards all modifications ofdata associated with thecurrent transaction and ends
the transaction.
Begins a new transaction.

EventsName

Description© 2019 DevartReferenceOccurs after the transaction
has been successfullycommitted.
Occurs after
CommitRetaining has been
executed.
Used to process errors that
occur during executing atransaction.
Occurs after the transaction
has been successfully rolledback.
Occurs after
RollbackRetaining has been
executed.

OnCommit

OnCommitRetaining

OnError

OnRollback

OnRollbackRetaining© 1997-2019
Devart. All Rights
Reserved.

489

Request Support

DAC Forum

Provide Feedback

5.10.1.18.2 Properties

Properties of the TDATransaction class.
For a complete list of the TDATransaction class members, see the TDATransaction
Members topic.

PublicName

Description
Used to determine if thetransaction is active.
Used to specify thetransaction behaviour when
it is destroyed while being
active, or when one of its
connections is closed withthe active transaction.

ActiveDefaultCloseAction

See Also
TDATransaction Class
TDATransaction Class Members© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

490

SQL Server Data Access Components

5.10.1.18.2.1 Active Property

Used to determine if the transaction is active.

Class
TDATransaction

Syntaxproperty Active: boolean;

Remarks
Indicates whether the transaction is active. This property is read-only.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.2.2 DefaultCloseAction Property

Used to specify the transaction behaviour when it is destroyed while being active, or when
one of its connections is closed with the active transaction.

Class
TDATransaction

Syntaxproperty DefaultCloseAction: TCRTransactionAction default
taRollback;Remarks
Use DefaultCloseAction to specify the transaction behaviour when it is destroyed while being
active, or when one of its connections is closed with the active transaction.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.3 Methods

Methods of the TDATransaction class.
For a complete list of the TDATransaction class members, see the TDATransaction
Members topic.

© 2019 DevartReference

491

PublicName

Description
Commits the current
transaction.
Discards all modifications ofdata associated with thecurrent transaction and ends
the transaction.
Begins a new transaction.

CommitRollback
StartTransaction

See Also
TDATransaction Class
TDATransaction Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.3.1 Commit Method

Commits the current transaction.

Class
TDATransaction

Syntax
procedure Commit; virtual;

Remarks
Call the Commit method to commit the current transaction. On commit server writes
permanently all pending data updates associated with the current transaction to the database,and then finishes the transaction.

See Also
Rollback
StartTransaction© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

492

SQL Server Data Access Components

5.10.1.18.3.2 Rollback Method

Discards all modifications of data associated with the current transaction and ends thetransaction.

Class
TDATransaction

Syntax
procedure Rollback; virtual;

Remarks
Call Rollback to cancel all data modifications made within the current transaction across all
database connections, and finish the transaction.

See Also
CommitStartTransaction© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.3.3 StartTransaction Method

Begins a new transaction.

Class
TDATransaction

Syntax
procedure StartTransaction; virtual;

Remarks
Call the StartTransaction method to begin a new transaction against the database server.
Before calling StartTransaction, an application should check the Active property. If
TDATransaction.Active is True, indicating that a transaction is already in progress, a
subsequent call to StartTransaction will raise EDatabaseError. An active transaction must be
finished by call to Commit or Rollback before call to StartTransaction. Call to StartTransaction
when connection is closed also will raise EDatabaseError.
Updates, insertions, and deletions that take place after a call to StartTransaction are held by© 2019 DevartReference493

the server until the application calls Commit to save the changes, or Rollback to cancel them.

See Also
CommitRollback© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.4 Events

Events of the TDATransaction class.
For a complete list of the TDATransaction class members, see the TDATransaction
Members topic.

PublicName

Description
Occurs after the transaction
has been successfullycommitted.
Occurs after
CommitRetaining has been
executed.
Used to process errors that
occur during executing atransaction.
Occurs after the transaction
has been successfully rolledback.
Occurs after
RollbackRetaining has been
executed.

OnCommit

OnCommitRetaining

OnError

OnRollback

OnRollbackRetaining

See Also
TDATransaction Class
TDATransaction Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

494

SQL Server Data Access Components

5.10.1.18.4.1 OnCommit Event

Occurs after the transaction has been successfully committed.

Class
TDATransaction

Syntaxproperty OnCommit: TNotifyEvent;Remarks
The OnCommit event fires when the M:Devart.Dac.TDATransaction.Commit method is
executed, just after the transaction is successfully committed. In order to respond to the
M:Devart.Sdac.TMSTransaction.CommitRetaining() method execution, theOnCommitRetaining event is used. When an error occurs during commit, the OnError event
fires.

See Also
Commit
M:Devart.Sdac.TMSTransaction.CommitRetaining()
OnCommitRetaining
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.4.2 OnCommitRetaining Event

Occurs after CommitRetaining has been executed.

Class
TDATransaction

Syntaxproperty OnCommitRetaining: TNotifyEvent;Remarks
The OnCommitRetaining event fires when the
M:Devart.Sdac.TMSTransaction.CommitRetaining() method is executed, just after the© 2019 DevartReference

495

transaction is successfully committed. In order to respond to the
M:Devart.Dac.TDATransaction.Commit method execution, the OnCommit event is used.
When an error occurs during commit, the OnError event fired.

See Also
M:Devart.Sdac.TMSTransaction.CommitRetaining()
Commit
OnCommit
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.4.3 OnError Event

Used to process errors that occur during executing a transaction.

Class
TDATransaction

Syntaxproperty OnError: TDATransactionErrorEvent;Remarks
Add a handler to the OnError event to process errors that occur during executing atransaction control statements such as Commit, Rollback. Check the E parameter to get theerror code.

See Also
CommitRollback
StartTransaction© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.18.4.4 OnRollback Event

Occurs after the transaction has been successfully rolled back.

Class© 2019 Devart

Provide Feedback

496

SQL Server Data Access Components

TDATransaction

Syntaxproperty OnRollback: TNotifyEvent;Remarks
The OnRollback event fires when the M:Devart.Dac.TDATransaction.Rollback method is
executed, just after the transaction is successfully rolled back. In order to respond to the
M:Devart.Sdac.TMSTransaction.RollbackRetaining() method execution, theOnRollbackRetaining event is used.
When an error occurs during rollback, the OnError event fired.

See Also
Rollback
M:Devart.Sdac.TMSTransaction.RollbackRetaining()
OnRollbackRetaining
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.18.4.5 OnRollbackRetaining Event

Occurs after RollbackRetaining has been executed.

Class
TDATransaction

Syntaxproperty OnRollbackRetaining: TNotifyEvent;Remarks
The OnRollbackRetaining event fires when the
M:Devart.Sdac.TMSTransaction.RollbackRetaining() method is executed, just after thetransaction is successfully rolled back. In order to respond to the
M:Devart.Dac.TDATransaction.Rollback method execution, the OnRollback event is used.
When an error occurs during rollback, the OnError event fired.

See Also© 2019 DevartReference

497

Rollback
M:Devart.Sdac.TMSTransaction.RollbackRetaining()
OnRollback
OnError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19 TMacro Class

Object that represents the value of a macro.
For a list of all members of this type, see TMacro members.

Unit
DBAccess

SyntaxTMacro = class(TCollectionItem);Remarks
TMacro object represents the value of a macro. Macro is a variable that holds string value.
You just insert & MacroName in a SQL query text and change the value of macro by the
Macro property editor at design time or the Value property at run time. At the time of opening
query macro is replaced by its value.
If by any reason it is not convenient for you to use the ' & ' symbol as a character of macro
replacement, change the value of the MacroChar variable.

See Also
TMacros© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.1 Members

TMacro class overview.

Properties
Name© 2019 Devart

Description

498

SQL Server Data Access Components

Used to determine if themacro should be expanded.
Used to set the TDataTime
value to a macro.
Used to set the float value toa macro.
Used to set the integer value
to a macro.
Used to assign the stringvalue to a macro.
Used to identify a particularmacro.
Used to set the value to a
macro.

ActiveAsDateTime
AsFloat
AsInteger
AsString
Name
Value© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.2 Properties

Properties of the TMacro class.
For a complete list of the TMacro class members, see the TMacro Members topic.

PublicName
AsDateTime
AsFloat
AsInteger
AsString

Description
Used to set the TDataTime
value to a macro.
Used to set the float value toa macro.
Used to set the integer value
to a macro.
Used to assign the stringvalue to a macro.

Published
Name
ActiveName

Description
Used to determine if themacro should be expanded.
Used to identify a particularmacro.

© 2019 DevartReference

499

Used to set the value to a
macro.

Value

See Also
TMacro Class
TMacro Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.2.1 Active Property

Used to determine if the macro should be expanded.

Class
TMacroSyntaxproperty Active: boolean default True;

Remarks
When set to True, the macro will be expanded, otherwise macro definition is replaced by null
string. You can use the Active property to modify the SQL property.
The default value is True.

ExampleMSQuery.SQL.Text := 'SELECT * FROM Dept WHERE DeptNo > 20 &Cond1';
MSQuery.Macros[0].Value := 'and DName is NULL';
MSQuery.Macros[0].Active:= False;© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.19.2.2 AsDateTime Property

Used to set the TDataTime value to a macro.

Class
TMacroSyntax© 2019 Devart

DAC Forum

Provide Feedback

500

SQL Server Data Access Components

property AsDateTime: TDateTime;

Remarks
Use the AsDataTime property to set the TDataTime value to a macro.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.2.3 AsFloat Property

Used to set the float value to a macro.

Class
TMacroSyntaxproperty AsFloat: double;

Remarks
Use the AsFloat property to set the float value to a macro.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.2.4 AsInteger Property

Used to set the integer value to a macro.

Class
TMacroSyntaxproperty AsInteger: integer;

Remarks
Use the AsInteger property to set the integer value to a macro.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

501

5.10.1.19.2.5 AsString Property

Used to assign the string value to a macro.

Class
TMacroSyntaxproperty AsString: string;

Remarks
Use the AsString property to assign the string value to a macro. Read the AsString property todetermine the value of macro represented as a string.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.19.2.6 Name Property

Used to identify a particular macro.

Class
TMacroSyntaxproperty Name: string;

Remarks
Use the Name property to identify a particular macro.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.10.1.19.2.7 Value Property

Used to set the value to a macro.

Class
TMacroSyntax© 2019 Devart

DAC Forum

Provide Feedback

502

SQL Server Data Access Components

property Value: string;

Remarks
Use the Value property to set the value to a macro.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20 TMacros Class

Controls a list of TMacro objects for the TCustomDASQL.Macros or TCustomDADataSet
components.
For a list of all members of this type, see TMacros members.

Unit
DBAccess

SyntaxTMacros = class(TCollection);

Remarks
Use TMacros to manage a list of TMacro objects for the TCustomDASQL or
TCustomDADataSet components.

See Also
TMacro© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20.1 Members

TMacros class overview.

Properties
Name
Items

Description
Used to iterate through all
the macros parameters.

Methods© 2019 DevartReference

Name

Description
Copies the macros values
and properties from thespecified source.
Changes the macros in thepassed SQL statement totheir values.
Searches for a TMacroobject by its name.
Compares itself with another
TMacro object.
Used to search for a macrowith the specified name.
Creates a macros from thepassed SQL statement.

AssignValues

ExpandFindMacro
IsEqualMacroByName
Scan© 1997-2019
Devart. All Rights
Reserved.

503

Request Support

DAC Forum

Provide Feedback

5.10.1.20.2 Properties

Properties of the TMacros class.
For a complete list of the TMacros class members, see the TMacros Members topic.

PublicName

Description
Used to iterate through all
the macros parameters.

Items

See Also
TMacros Class
TMacros Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.20.2.1 Items Property(Indexer)

Used to iterate through all the macros parameters.

Class
TMacros© 2019 Devart

Provide Feedback

504

SQL Server Data Access Components

Syntaxproperty Items[Index: integer]: TMacro; default;
Parameters
Index
Holds the index in the range 0..Count - 1.

Remarks
Use the Items property to iterate through all macros parameters. Index identifies the index in
the range 0..Count - 1.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20.3 Methods

Methods of the TMacros class.
For a complete list of the TMacros class members, see the TMacros Members topic.

PublicName

Description
Copies the macros values
and properties from thespecified source.
Changes the macros in thepassed SQL statement totheir values.
Searches for a TMacroobject by its name.
Compares itself with another
TMacro object.
Used to search for a macrowith the specified name.
Creates a macros from thepassed SQL statement.

AssignValues

ExpandFindMacro
IsEqualMacroByName
Scan

See Also
TMacros Class
TMacros Class Members© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

505

Devart. All Rights
Reserved.
5.10.1.20.3.1 AssignValues Method

Copies the macros values and properties from the specified source.

Class
TMacros

Syntax
procedure AssignValues(Value: TMacros);Parameters
Value
Holds the source to copy the macros values and properties from.

Remarks
The Assign method copies the macros values and properties from the specified source.
Macros are not recreated. Only the values of macros with matching names are assigned.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20.3.2 Expand Method

Changes the macros in the passed SQL statement to their values.

Class
TMacros

Syntax
procedure Expand(var SQL: string);
Parameters
SQL
Holds the passed SQL statement.

Remarks
Call the Expand method to change the macros in the passed SQL statement to their values.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

506

SQL Server Data Access Components

Reserved.
5.10.1.20.3.3 FindMacro Method

Searches for a TMacro object by its name.

Class
TMacros

Syntaxfunction FindMacro(const Value: string): TMacro;Parameters
Value
Holds the value of a macro to search for.
Return Value
TMacro object if a match was found, nil otherwise.

Remarks
Call the FindMacro method to find a macro with the name passed in Value. If a match isfound, FindMacro returns the macro. Otherwise, it returns nil. Use this method rather than adirect reference to the Items property to avoid depending on the order of the entries.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20.3.4 IsEqual Method

Compares itself with another TMacro object.

Class
TMacros

Syntaxfunction IsEqual(Value: TMacros): boolean;
Parameters
Value
Holds the values of TMacro objects.
Return Value
True, if the number of TMacro objects and the values of all TMacro objects are equal.

© 2019 DevartReference

507

Remarks
Call the IsEqual method to compare itself with another TMacro object. Returns True if thenumber of TMacro objects and the values of all TMacro objects are equal.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.20.3.5 MacroByName Method

Used to search for a macro with the specified name.

Class
TMacros

Syntaxfunction MacroByName(const Value: string): TMacro;Parameters
Value
Holds a name of the macro to search for.
Return Value
TMacro object, if a macro with specified name was found.

Remarks
Call the MacroByName method to find a Macro with the name passed in Value. If a match isfound, MacroByName returns the Macro. Otherwise, an exception is raised. Use this method
rather than a direct reference to the Items property to avoid depending on the order of theentries.
To locate a macro by name without raising an exception if the parameter is not found, use the
FindMacro method.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.20.3.6 Scan Method

Creates a macros from the passed SQL statement.

Class
TMacros© 2019 Devart

Provide Feedback

508

SQL Server Data Access Components

Syntax
procedure Scan(const SQL: string);
Parameters
SQL
Holds the passed SQL statement.

Remarks
Call the Scan method to create a macros from the passed SQL statement. On that allexisting TMacro objects are cleared.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.21 TPoolingOptions ClassThis class allows setting up the behaviour of the connection pool.
For a list of all members of this type, see TPoolingOptions members.

Unit
DBAccess

Syntax
TPoolingOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.21.1 Members

TPoolingOptions class overview.

Properties
Name
ConnectionLifetime

MaxPoolSize

Description
Used to specify the
maximum time during which
an opened connection canbe used by connection pool.
Used to specify the
maximum number ofconnections that can be© 2019 DevartReference

opened in connection pool.
Used to specify theminimum number ofconnections that can be
opened in the connection
pool.
Used for a connection to bevalidated when it is returned
from the pool.

MinPoolSize

Validate© 1997-2019
Devart. All Rights
Reserved.

509

Request Support

DAC Forum

Provide Feedback

5.10.1.21.2 Properties

Properties of the TPoolingOptions class.
For a complete list of the TPoolingOptions class members, see the TPoolingOptions
Members topic.

Published
Name

Description
Used to specify the
maximum time during which
an opened connection canbe used by connection pool.
Used to specify the
maximum number ofconnections that can be
opened in connection pool.
Used to specify theminimum number ofconnections that can be
opened in the connection
pool.
Used for a connection to bevalidated when it is returned
from the pool.

ConnectionLifetime

MaxPoolSize

MinPoolSize

Validate

See Also
TPoolingOptions Class
TPoolingOptions Class Members© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

510

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.10.1.21.2.1 ConnectionLifetime Property

Used to specify the maximum time during which an opened connection can be used byconnection pool.

Class
TPoolingOptions

Syntaxproperty ConnectionLifetime: integer default
DefValConnectionLifetime;

Remarks
Use the ConnectionLifeTime property to specify the maximum time during which an opened
connection can be used by connection pool. Measured in milliseconds. Pool deletesconnections with exceeded connection lifetime when TCustomDAConnection is about toclose. If the ConnectionLifetime property is set to 0 (by default), then the lifetime of connection
is infinity. ConnectionLifetime concerns only inactive connections in the pool.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.21.2.2 MaxPoolSize Property

Used to specify the maximum number of connections that can be opened in connection pool.

Class
TPoolingOptions

Syntaxproperty MaxPoolSize: integer default DefValMaxPoolSize;

Remarks
Specifies the maximum number of connections that can be opened in connection pool. Once
this value is reached, no more connections are opened. The valid values are 1 and higher.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

511

5.10.1.21.2.3 MinPoolSize Property

Used to specify the minimum number of connections that can be opened in the connection
pool.

Class
TPoolingOptions

Syntaxproperty MinPoolSize: integer default DefValMinPoolSize;

Remarks
Use the MinPoolSize property to specify the minimum number of connections that can be
opened in the connection pool.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.21.2.4 Validate Property

Used for a connection to be validated when it is returned from the pool.

Class
TPoolingOptions

Syntaxproperty Validate: boolean default DefValValidate;

Remarks
If the Validate property is set to True, connection will be validated when it is returned from thepool. By default this option is set to False and pool does not validate connection when it isreturned to be used by a TCustomDAConnection component.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22 TSmartFetchOptions Class

Smart fetch options are used to set up the behavior of the SmartFetch mode.
For a list of all members of this type, see TSmartFetchOptions members.

© 2019 Devart

512

SQL Server Data Access Components

Unit
DBAccess

SyntaxTSmartFetchOptions = class(TPersistent);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22.1 Members

TSmartFetchOptions class overview.

Properties
Name

Description
Sets SmartFetch mode
enabled or not.
Used to minimize memory
consumption.
List of fields additional to
key fields that will be readfrom the database on
dataset open.
SQL query for the read key
and prefetched fields fromthe database.

Enabled
LiveBlockPrefetchedFields

SQLGetKeyValues© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22.2 Properties

Properties of the TSmartFetchOptions class.
For a complete list of the TSmartFetchOptions class members, see theTSmartFetchOptions Members topic.

Published
Name
EnabledDescription
Sets SmartFetch mode
enabled or not.
© 2019 DevartReference

513

Used to minimize memory
consumption.
List of fields additional to
key fields that will be readfrom the database on
dataset open.
SQL query for the read key
and prefetched fields fromthe database.

LiveBlockPrefetchedFields

SQLGetKeyValues

See Also
TSmartFetchOptions Class
TSmartFetchOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22.2.1 Enabled Property

Sets SmartFetch mode enabled or not.

Class
TSmartFetchOptions

Syntaxproperty Enabled: Boolean default False;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.10.1.22.2.2 LiveBlock Property

Used to minimize memory consumption.

Class
TSmartFetchOptions

Syntaxproperty LiveBlock: Boolean default True;

Remarks© 2019 Devart

Provide Feedback

514

SQL Server Data Access Components

If LiveBlock is True, then on navigating through a dataset forward or backward, memory willbe allocated for records count defined in the the FetchRows propety, and no additional
memory will be allocated. But if you return records that were read from the database before,
they will be read from the database again, because when you left block with these records,
memory was free. So the LiveBlock mode minimizes memory consumption, but candecrease performance, because it can lead to repeated data reading from the database.
The default value of LiveBlock is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22.2.3 PrefetchedFields Property

List of fields additional to key fields that will be read from the database on dataset open.

Class
TSmartFetchOptions

Syntaxproperty PrefetchedFields: string;

Remarks
If you are going to use locate, filter or sort by some fields, then these fields should be added tothe prefetched fields list to avoid excessive reading from the database.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.1.22.2.4 SQLGetKeyValues Property

SQL query for the read key and prefetched fields from the database.

Class
TSmartFetchOptions

Syntaxproperty SQLGetKeyValues: TStrings;

Remarks
SQLGetKeyValues is used when the basic SQL query is complex and the query for reading© 2019 DevartReference

515

the key and prefetched fields can't be generated automatically.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2 Types
Types in the DBAccess unit.

Types
Name

Description
This type is used for the
TCustomDADataSet.AfterE
xecute andTCustomDASQL.AfterExecu
te events.
This type is used for the
TCustomDADataSet.AfterF
etch event.
This type is used for the
TCustomDADataSet.Before
Fetch event.
This type is used for the
TCustomDAConnection.On
ConnectionLost event.
This type is used for the
TCustomDAConnection.On
Error event.
This type is used for the
TDATransaction.OnError
event.
Represents the set of
TRefreshOption.
This type is used for the
TCustomDADataSet.AfterU
pdateExecute andTCustomDADataSet.Before
UpdateExecute events.

TAfterExecuteEvent

TAfterFetchEvent

TBeforeFetchEvent

TConnectionLostEvent

TDAConnectionErrorEvent

TDATransactionErrorEvent
TRefreshOptions

TUpdateExecuteEvent© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

516

SQL Server Data Access Components

5.10.2.1 TAfterExecuteEvent Procedure ReferenceThis type is used for the TCustomDADataSet.AfterExecute andTCustomDASQL.AfterExecute events.

Unit
DBAccess

SyntaxTAfterExecuteEvent = procedure (Sender: TObject; Result: boolean)of object;Parameters
SenderAn object that raised the event.
Result
The result is True if SQL statement is executed successfully. False otherwise.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2.2 TAfterFetchEvent Procedure ReferenceThis type is used for the TCustomDADataSet.AfterFetch event.

Unit
DBAccess

SyntaxTAfterFetchEvent = procedure (DataSet: TCustomDADataSet) of
object;Parameters
DataSetHolds the TCustomDADataSet descendant to synchronize the record position with.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

517

5.10.2.3 TBeforeFetchEvent Procedure ReferenceThis type is used for the TCustomDADataSet.BeforeFetch event.

Unit
DBAccess

SyntaxTBeforeFetchEvent = procedure (DataSet: TCustomDADataSet; var
Cancel: boolean) of object;Parameters
DataSetHolds the TCustomDADataSet descendant to synchronize the record position with.
CancelTrue, if the current fetch operation should be aborted.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2.4 TConnectionLostEvent Procedure ReferenceThis type is used for the TCustomDAConnection.OnConnectionLost event.

Unit
DBAccess

SyntaxTConnectionLostEvent = procedure (Sender: TObject; Component:
TComponent; ConnLostCause: TConnLostCause; var RetryMode:
TRetryMode) of object;Parameters
SenderAn object that raised the event.
Component
ConnLostCause
The reason of the connection loss.
RetryMode
The application behavior when connection is lost.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

518

SQL Server Data Access Components

Reserved.
5.10.2.5 TDAConnectionErrorEvent Procedure ReferenceThis type is used for the TCustomDAConnection.OnError event.

Unit
DBAccess

SyntaxTDAConnectionErrorEvent = procedure (Sender: TObject; E: EDAError;
var Fail: boolean) of object;Parameters
SenderAn object that raised the event.
E
The error information.
Fail
False, if an error dialog should be prevented from being displayed and EAbort exception
should be raised to cancel current operation .

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2.6 TDATransactionErrorEvent Procedure ReferenceThis type is used for the TDATransaction.OnError event.

Unit
DBAccess

SyntaxTDATransactionErrorEvent = procedure (Sender: TObject; E:
EDAError; var Fail: boolean) of object;Parameters
SenderAn object that raised the event.
E
The error code.
Fail© 2019 DevartReference

519

False, if an error dialog should be prevented from being displayed and EAbort exception tocancel the current operation should be raised.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2.7 TRefreshOptions Set

Represents the set of TRefreshOption.

Unit
DBAccess

SyntaxTRefreshOptions = set of TRefreshOption;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.2.8 TUpdateExecuteEvent Procedure ReferenceThis type is used for the TCustomDADataSet.AfterUpdateExecute andTCustomDADataSet.BeforeUpdateExecute events.

Unit
DBAccess

SyntaxTUpdateExecuteEvent = procedure (Sender: TDataSet; StatementTypes:
TStatementTypes; Params: TDAParams) of object;Parameters
SenderAn object that raised the event.
StatementTypes
Holds the type of the SQL statement being executed.
ParamsHolds the parameters with which the SQL statement will be executed.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

520

SQL Server Data Access Components

5.10.3 Enumerations
Enumerations in the DBAccess unit.

Enumerations
Name

Description
Sets the languauge of labelsin the connect dialog.
Indicates when the editing
record will be refreshed.
Specifies the application
behavior when connection islost.

TLabelSet
TRefreshOption
TRetryMode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.3.1 TLabelSet Enumeration

Sets the languauge of labels in the connect dialog.

Unit
DBAccess

SyntaxTLabelSet = (lsCustom, lsEnglish, lsFrench, lsGerman, lsItalian,lsPolish, lsPortuguese, lsRussian, lsSpanish);

ValuesValue
lsCustomlsEnglish
lsFrenchlsGermanlsItalianlsPolishlsPortuguese
lsRussianlsSpanish© 1997-2019

Meaning
Set the language of labels in the connect dialog manually.
Set English as the language of labels in the connect dialog.
Set French as the language of labels in the connect dialog.
Set German as the language of labels in the connect dialog.
Set Italian as the language of labels in the connect dialog.
Set Polish as the language of labels in the connect dialog.
Set Portuguese as the language of labels in the connect dialog.
Set Russian as the language of labels in the connect dialog.
Set Spanish as the language of labels in the connect dialog.
Request Support
DAC Forum
Provide Feedback© 2019 DevartReference

521

Devart. All Rights
Reserved.
5.10.3.2 TRefreshOption Enumeration

Indicates when the editing record will be refreshed.

Unit
DBAccess

SyntaxTRefreshOption = (roAfterInsert, roAfterUpdate, roBeforeEdit);ValuesValue
roAfterInsert
roAfterUpdate
roBeforeEdit© 1997-2019
Devart. All Rights
Reserved.

Meaning
Refresh is performed after inserting.
Refresh is performed after updating.
Refresh is performed by Edit method.
Request Support

DAC Forum

Provide Feedback

5.10.3.3 TRetryMode Enumeration

Specifies the application behavior when connection is lost.

Unit
DBAccess

SyntaxTRetryMode = (rmRaise, rmReconnect, rmReconnectExecute);

ValuesValue
MeaningrmRaiseAn exception is raised.
rmReconnect
Reconnect is performed and then exception is raised.
rmReconnectExec Reconnect is performed and abortive operation is reexecuted.
ute
Exception is not raised.
© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

522

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.10.4 Variables
Variables in the DBAccess unit.

Variables
Name

Description
After assigning SQL text andmodifying it by AddWhere,
DeleteWhere, and
SetOrderBy, all subsequentchanges of the SQL property
will not be reflected in the
BaseSQL property.
When set to True allows
data access components tochange screen cursor for the
execution time.
The value of theTCustomDADataSet.BaseSQL property is used tocomplete the refresh SQL
statement, if the manuallyassigned
TCustomDAUpdateSQL.Ref
reshSQL property contains
only WHERE clause.

BaseSQLOldBehavior

ChangeCursor

SQLGeneratorCompatibility© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.4.1 BaseSQLOldBehavior Variable

After assigning SQL text and modifying it by AddWhere, DeleteWhere, and SetOrderBy, allsubsequent changes of the SQL property will not be reflected in the BaseSQL property.

Unit
DBAccess

SyntaxBaseSQLOldBehavior: boolean = False;© 2019 DevartReference

523

Remarks
The BaseSQL property is similar to the SQL property, but it does not store changes made by
the AddWhere, DeleteWhere, and SetOrderBy methods. After assigning SQL text andmodifying it by one of these methods, all subsequent changes of the SQL property will not bereflected in the BaseSQL property. This behavior was changed in SDAC 3.55.2.22. To restore
old behavior, set the BaseSQLOldBehavior variable to True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.4.2 ChangeCursor Variable

When set to True allows data access components to change screen cursor for the execution
time.

Unit
DBAccess

SyntaxChangeCursor: boolean = True;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.10.4.3 SQLGeneratorCompatibility Variable

The value of the TCustomDADataSet.BaseSQL property is used to complete the refresh SQL
statement, if the manually assigned TCustomDAUpdateSQL.RefreshSQL property contains
only WHERE clause.

Unit
DBAccess

SyntaxSQLGeneratorCompatibility: boolean = False;

Remarks
If the manually assigned TCustomDAUpdateSQL.RefreshSQL property contains only
WHERE clause, SDAC uses the value of the TCustomDADataSet.BaseSQL property to© 2019 Devart

524

SQL Server Data Access Components

complete the refresh SQL statement. In this situation all modifications applied to the SELECT
query by functions TCustomDADataSet.AddWhere, TCustomDADataSet.DeleteWhere are
not taken into account. This behavior was changed in SDAC 4.00.0.4. To restore the oldbehavior, set the BaseSQLOldBehavior variable to True.

© 1997-2019
Devart. All Rights
Reserved.

5.11

Request Support

DAC Forum

Provide Feedback

MemDataThis unit contains classes for storing data in memory.

ClassesName
TAttribute
TBlob

TCompressedBlob

TDBObject
TMemData
TObjectType

TSharedObject

Description
TAttribute is not used in
SDAC.
Holds large object value forfield and parameter dtBlob,
dtMemo data types.
Holds large object value forfield and parameter dtBlob,
dtMemo data types and cancompress its data.
A base class for classes thatwork with user-defined datatypes that have attributes.
Implements storing data inmemory.
This class is not used.
A base class that allows to
simplify memory
management for objectreferenced by several otherobjects.

Types
Name
TLocateExOptions
TUpdateRecKinds

Description
Represents the set of
TLocateExOption.
Represents the set of
TUpdateRecKind.
© 2019 DevartReference

525

Enumerations
Name

Description
Specifies when the values
should be compressed andthe way they should be
stored.
Specifies the cause of theconnection loss.
Specifies the format ofstoring and representing of
the NUMERIC (DECIMAL)
fields.
Allows to set additional
search parameters which
will be used by the LocateEx
method.
Specifies a sort type forstring fields.
Indicates records for which
the ApplyUpdates method
will be performed.

TCompressBlobMode

TConnLostCause

TDANumericType

TLocateExOption

TSortType
TUpdateRecKind© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1 Classes
Classes in the MemData unit.

ClassesName
TAttribute
TBlob

TCompressedBlob

TDBObject© 2019 Devart

Description
TAttribute is not used in
SDAC.
Holds large object value forfield and parameter dtBlob,
dtMemo data types.
Holds large object value forfield and parameter dtBlob,
dtMemo data types and cancompress its data.
A base class for classes that

526

SQL Server Data Access Components

work with user-defined datatypes that have attributes.
Implements storing data inmemory.
This class is not used.
A base class that allows to
simplify memory
management for objectreferenced by several otherobjects.

TMemData
TObjectType

TSharedObject© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1 TAttribute Class

TAttribute is not used in SDAC.
For a list of all members of this type, see TAttribute members.

Unit
MemData

SyntaxTAttribute = class(System.TObject);© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.1 Members

TAttribute class overview.

Properties
Name
AttributeNo
DataSize

DataType

Description
Returns an attribute's ordinal
position in object.
Returns the size of an
attribute value in internal
representation.
Returns the type of data that
was assigned to the
Attribute.
© 2019 DevartReference

Returns the length of thestring for dtString attributeand precision for dtInteger
and dtFloat attribute.
Returns a TObjectTypeobject for an object attribute.
Returns an offset of theattribute value in internal
representation.
Indicates TObjectType thatuses the attribute torepresent one of its
attributes.
Returns the scale of dtFloatand dtInteger attributes.
Returns the size of an
attribute value in external
representation.

LengthObjectType
Offset

Owner

Scale
Size
© 1997-2019
Devart. All Rights
Reserved.

527

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2 Properties

Properties of the TAttribute class.
For a complete list of the TAttribute class members, see the TAttribute Members topic.

PublicName
AttributeNo
DataSize

DataType

LengthObjectType© 2019 Devart

Description
Returns an attribute's ordinal
position in object.
Returns the size of an
attribute value in internal
representation.
Returns the type of data that
was assigned to the
Attribute.
Returns the length of thestring for dtString attributeand precision for dtInteger
and dtFloat attribute.
Returns a TObjectTypeobject for an object attribute.

528

SQL Server Data Access Components

Returns an offset of theattribute value in internal
representation.
Indicates TObjectType thatuses the attribute torepresent one of its
attributes.
Returns the scale of dtFloatand dtInteger attributes.
Returns the size of an
attribute value in external
representation.

Offset

Owner

Scale
Size

See Also
TAttribute Class
TAttribute Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.1 AttributeNo Property

Returns an attribute's ordinal position in object.

Class
TAttribute

Syntaxproperty AttributeNo: Word;

Remarks
Use the AttributeNo property to learn an attribute's ordinal position in object, where 1 is thefirst field.

See Also
TObjectType.Attributes© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference529

5.11.1.1.2.2 DataSize Property

Returns the size of an attribute value in internal representation.

Class
TAttribute

Syntaxproperty DataSize: Integer;

Remarks
Use the DataSize property to learn the size of an attribute value in internal representation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.3 DataType Property

Returns the type of data that was assigned to the Attribute.

Class
TAttribute

Syntaxproperty DataType: Word;

Remarks
Use the DataType property to discover the type of data that was assigned to the Attribute.
Possible values: dtDate, dtFloat, dtInteger, dtString, dtObject.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.4 Length Property

Returns the length of the string for dtString attribute and precision for dtInteger and dtFloat
attribute.

Class
TAttribute© 2019 Devart

530

SQL Server Data Access Components

Syntaxproperty Length: Word;

Remarks
Use the Length property to learn the length of the string for dtString attribute and precision for
dtInteger and dtFloat attribute.

See Also
Scale© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.5 ObjectType Property

Returns a TObjectType object for an object attribute.

Class
TAttribute

Syntaxproperty ObjectType: TObjectType;

Remarks
Use the ObjectType property to return a TObjectType object for an object attribute.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.6 Offset Property

Returns an offset of the attribute value in internal representation.

Class
TAttribute

Syntaxproperty Offset: Integer;© 2019 DevartReference

531

Remarks
Use the DataSize property to learn an offset of the attribute value in internal representation.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.7 Ow ner Property

Indicates TObjectType that uses the attribute to represent one of its attributes.

Class
TAttribute

Syntaxproperty Owner: TObjectType;

Remarks
Check the value of the Owner property to determine TObjectType that uses the attribute torepresent one of its attributes. Applications should not assign the Owner property directly.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.1.2.8 Scale Property

Returns the scale of dtFloat and dtInteger attributes.

Class
TAttribute

Syntaxproperty Scale: Word;

Remarks
Use the Scale property to learn the scale of dtFloat and dtInteger attributes.

See Also
Length© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

532

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.11.1.1.2.9 Size Property

Returns the size of an attribute value in external representation.

Class
TAttribute

Syntaxproperty Size: Integer;

Remarks
Read Size to learn the size of an attribute value in external representation.
For example:

dtDate8(sizeof(TDateTi
me)
8(sizeof(Double))4(sizeof(Integer))dtFloat
dtInteger

See Also
DataSize© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2 TBlob Class

Holds large object value for field and parameter dtBlob, dtMemo data types.
For a list of all members of this type, see TBlob members.

Unit
MemData

SyntaxTBlob = class(TSharedObject);© 2019 DevartReference

533

Remarks
Object TBlob holds large object value for the field and parameter dtBlob, dtMemo,dtWideMemo data types.

Inheritance Hierarchy
TSharedObject
TBlob

See Also
TMemDataSet.GetBlob© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.1 Members

TBlob class overview.

Properties
Name
AsString
AsWideString

IsUnicode

RefCount (inherited from TSharedObject)
Size

Description
Used to manipulate BLOB
value as string.
Used to manipulate BLOB
value as Unicode string.
Gives choice of making
TBlob store and processdata in Unicode format ornot.
Used to return the count ofreference to a
TSharedObject object.
Used to learn the size of the
TBlob value in bytes.

Methods
Name

Description

AddRef (inherited from TSharedObject)

Increments the reference
count for the number ofreferences dependent on the© 2019 Devart

534

SQL Server Data Access Components

TSharedObject object.
Sets BLOB value fromanother TBlob object.
Deletes the current value in
TBlob object.
Loads the contents of a file
into a TBlob object.
Copies the contents of a
stream into the TBlob object.
Acquires a raw sequence ofbytes from the data stored in
TBlob.
Decrements the reference
count.
Saves the contents of the
TBlob object to a file.
Copies the contents of a
TBlob object to a stream.
Sets new TBlob size anddiscards all data over it.
Stores a raw sequence ofbytes into a TBlob object.

AssignClear
LoadFromFile
LoadFromStream
Read
Release (inherited from TSharedObject)
SaveToFile
SaveToStream
Truncate
Write© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.2 Properties

Properties of the TBlob class.
For a complete list of the TBlob class members, see the TBlob Members topic.

PublicName
AsString
AsWideString

IsUnicode

RefCount (inherited from TSharedObject)

Description
Used to manipulate BLOB
value as string.
Used to manipulate BLOB
value as Unicode string.
Gives choice of making
TBlob store and processdata in Unicode format ornot.
Used to return the count ofreference to a
© 2019 DevartReference

535

TSharedObject object.
Used to learn the size of the
TBlob value in bytes.

Size

See Also
TBlob Class
TBlob Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.2.1 AsString Property

Used to manipulate BLOB value as string.

Class
TBlob

Syntaxproperty AsString: string;

Remarks
Use the AsString property to manipulate BLOB value as string.

See Also
AssignAsWideString© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.11.1.2.2.2 AsWideString Property

Used to manipulate BLOB value as Unicode string.

Class
TBlob

Syntaxproperty AsWideString: string;© 2019 Devart

Provide Feedback

536

SQL Server Data Access Components

Remarks
Use the AsWideString property to manipulate BLOB value as Unicode string.

See Also
AssignAsString© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.2.3 IsUnicode Property

Gives choice of making TBlob store and process data in Unicode format or not.

Class
TBlob

Syntaxproperty IsUnicode: boolean;

Remarks
Set IsUnicode to True if you want TBlob to store and process data in Unicode format.
Note: changing this property raises an exception if TBlob is not empty.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.2.4 Size Property

Used to learn the size of the TBlob value in bytes.

Class
TBlob

Syntaxproperty Size: Cardinal;

Remarks
Use the Size property to find out the size of the TBlob value in bytes.

© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

537

Provide Feedback

5.11.1.2.3 Methods

Methods of the TBlob class.
For a complete list of the TBlob class members, see the TBlob Members topic.

PublicName

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Sets BLOB value fromanother TBlob object.
Deletes the current value in
TBlob object.
Loads the contents of a file
into a TBlob object.
Copies the contents of a
stream into the TBlob object.
Acquires a raw sequence ofbytes from the data stored in
TBlob.
Decrements the reference
count.
Saves the contents of the
TBlob object to a file.
Copies the contents of a
TBlob object to a stream.
Sets new TBlob size anddiscards all data over it.
Stores a raw sequence ofbytes into a TBlob object.

AddRef (inherited from TSharedObject)

AssignClear
LoadFromFile
LoadFromStream
Read
Release (inherited from TSharedObject)
SaveToFile
SaveToStream
TruncateWrite

See Also
TBlob Class
TBlob Class Members© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

538

SQL Server Data Access Components

Reserved.
5.11.1.2.3.1 Assign Method

Sets BLOB value from another TBlob object.

Class
TBlob

Syntax
procedure Assign(Source: TBlob);
Parameters
SourceHolds the BLOB from which the value to the current object will be assigned.

Remarks
Call the Assign method to set BLOB value from another TBlob object.

See Also
LoadFromStream
AsString
AsWideString© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.2 Clear Method

Deletes the current value in TBlob object.

Class
TBlob

Syntax
procedure Clear; virtual;

Remarks
Call the Clear method to delete the current value in TBlob object.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

539

Reserved.
5.11.1.2.3.3 LoadFromFile Method

Loads the contents of a file into a TBlob object.

Class
TBlob

Syntax
procedure LoadFromFile(const FileName: string);
Parameters
FileName
Holds the name of the file from which the TBlob value is loaded.

Remarks
Call the LoadFromFile method to load the contents of a file into a TBlob object. Specify thename of the file to load into the field as the value of the FileName parameter.

See Also
SaveToFile© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.4 LoadFromStream Method

Copies the contents of a stream into the TBlob object.

Class
TBlob

Syntax
procedure LoadFromStream(Stream: TStream); virtual;Parameters
StreamHolds the specified stream from which the field's value is copied.

Remarks© 2019 Devart

540

SQL Server Data Access Components

Call the LoadFromStream method to copy the contents of a stream into the TBlob object.
Specify the stream from which the field's value is copied as the value of the Stream
parameter.

See Also
SaveToStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.5 Read Method

Acquires a raw sequence of bytes from the data stored in TBlob.

Class
TBlob

Syntaxfunction Read(Position: Cardinal; Count: Cardinal; Dest: IntPtr):
Cardinal; virtual;Parameters
Position
Holds the starting point of the byte sequence.
Count
Holds the size of the sequence in bytes.
Dest
Holds a pointer to the memory area where to store the sequence.
Return Value
Actually read byte count if the sequence crosses object size limit.

Remarks
Call the Read method to acquire a raw sequence of bytes from the data stored in TBlob.
The Position parameter is the starting point of byte sequence which lasts Count number ofbytes. The Dest parameter is a pointer to the memory area where to store the sequence.
If the sequence crosses object size limit, function will return actually read byte count.

See Also
Write© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference541

Devart. All Rights
Reserved.
5.11.1.2.3.6 SaveToFile Method

Saves the contents of the TBlob object to a file.

Class
TBlob

Syntax
procedure SaveToFile(const FileName: string);
Parameters
FileName
Holds a string that contains the name of the file.

Remarks
Call the SaveToFile method to save the contents of the TBlob object to a file. Specify thename of the file as the value of the FileName parameter.

See Also
LoadFromFile© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.7 SaveToStream Method

Copies the contents of a TBlob object to a stream.

Class
TBlob

Syntax
procedure SaveToStream(Stream: TStream); virtual;Parameters
StreamHolds the name of the stream.

Remarks© 2019 Devart

542

SQL Server Data Access Components

Call the SaveToStream method to copy the contents of a TBlob object to a stream. Specify
the name of the stream to which the field's value is saved as the value of the Stream
parameter.

See Also
LoadFromStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.8 Truncate Method

Sets new TBlob size and discards all data over it.

Class
TBlob

Syntax
procedure Truncate(NewSize: Cardinal); virtual;Parameters
NewSize
Holds the new size of TBlob.

Remarks
Call the Truncate method to set new TBlob size and discard all data over it. If NewSize isgreater or equal TBlob.Size, it does nothing.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.2.3.9 Write Method

Stores a raw sequence of bytes into a TBlob object.

Class
TBlob

Syntax
procedure Write(Position: Cardinal; Count: Cardinal; Source:
IntPtr); virtual;© 2019 DevartReference

543

Parameters
Position
Holds the starting point of the byte sequence.
Count
Holds the size of the sequence in bytes.
SourceHolds a pointer to a source memory area.

Remarks
Call the Write method to store a raw sequence of bytes into a TBlob object.
The Position parameter is the starting point of byte sequence which lasts Count number ofbytes. The Source parameter is a pointer to a source memory area.
If the value of the Position parameter crosses current size limit of TBlob object, source data
will be appended to the object data.

See Also
Read© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.3 TCompressedBlob Class

Holds large object value for field and parameter dtBlob, dtMemo data types and cancompress its data.
For a list of all members of this type, see TCompressedBlob members.

Unit
MemData

SyntaxTCompressedBlob = class(TBlob);

Remarks
TCompressedBlob is a descendant of the TBlob class. It holds large object value for field andparameter dtBlob, dtMemo data types and can compress its data. For more information about
using BLOB compression see TCustomDADataSet.Options.
Note: Internal compression functions are available in CodeGear Delphi 2007 for Win32,
Borland Developer Studio 2006, Borland Delphi 2005, and Borland Delphi 7. To use BLOB

© 2019 Devart

544

SQL Server Data Access Components

compression under Borland Delphi 6 and Borland C++ Builder you should use your own
compression functions. To use them set the CompressProc and UncompressProc variables
declared in the MemUtils unit.

Exampletype
TCompressProc = function(dest: IntPtr; destLen: IntPtr; const source: In
TUncompressProc = function(dest: IntPtr; destlen: IntPtr; source: IntPtr
var
CompressProc: TCompressProc;
UncompressProc: TUncompressProc;

Inheritance Hierarchy
TSharedObject
TBlob
TCompressedBlob

See Also
TBlob
TMemDataSet.GetBlob
TCustomDADataSet.Options© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.3.1 Members

TCompressedBlob class overview.

Properties
Name
AsString (inherited from TBlob)
AsWideString (inherited from TBlob)
Compressed
CompressedSize
IsUnicode (inherited from TBlob)

Description
Used to manipulate BLOB
value as string.
Used to manipulate BLOB
value as Unicode string.
Used to indicate if the Blob
is compressed.
Used to indicatecompressed size of the Blob
data.
Gives choice of making
TBlob store and process© 2019 DevartReference

545

data in Unicode format ornot.
Used to return the count ofreference to a
TSharedObject object.
Used to learn the size of the
TBlob value in bytes.

RefCount (inherited from TSharedObject)
Size (inherited from TBlob)

Methods
Name

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Sets BLOB value fromanother TBlob object.
Deletes the current value in
TBlob object.
Loads the contents of a file
into a TBlob object.
Copies the contents of a
stream into the TBlob object.
Acquires a raw sequence ofbytes from the data stored in
TBlob.
Decrements the reference
count.
Saves the contents of the
TBlob object to a file.
Copies the contents of a
TBlob object to a stream.
Sets new TBlob size anddiscards all data over it.
Stores a raw sequence ofbytes into a TBlob object.

AddRef (inherited from TSharedObject)

Assign (inherited from TBlob)
Clear (inherited from TBlob)
LoadFromFile (inherited from TBlob)
LoadFromStream (inherited from TBlob)
Read (inherited from TBlob)
Release (inherited from TSharedObject)
SaveToFile (inherited from TBlob)
SaveToStream (inherited from TBlob)
Truncate (inherited from TBlob)
Write (inherited from TBlob)© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

546

SQL Server Data Access Components

5.11.1.3.2 Properties

Properties of the TCompressedBlob class.
For a complete list of the TCompressedBlob class members, see the TCompressedBlob
Members topic.

PublicName

Description
Used to manipulate BLOB
value as string.
Used to manipulate BLOB
value as Unicode string.
Used to indicate if the Blob
is compressed.
Used to indicatecompressed size of the Blob
data.
Gives choice of making
TBlob store and processdata in Unicode format ornot.
Used to return the count ofreference to a
TSharedObject object.
Used to learn the size of the
TBlob value in bytes.

AsString (inherited from TBlob)
AsWideString (inherited from TBlob)
Compressed
CompressedSize

IsUnicode (inherited from TBlob)

RefCount (inherited from TSharedObject)
Size (inherited from TBlob)

See Also
TCompressedBlob Class
TCompressedBlob Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.3.2.1 Compressed Property

Used to indicate if the Blob is compressed.

Class
TCompressedBlob

Syntax© 2019 DevartReference547

property Compressed: boolean;

Remarks
Indicates whether the Blob is compressed. Set this property to True or False to compress or
decompress the Blob.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.3.2.2 CompressedSize Property

Used to indicate compressed size of the Blob data.

Class
TCompressedBlob

Syntaxproperty CompressedSize: Cardinal;

Remarks
Indicates compressed size of the Blob data.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.4 TDBObject ClassA base class for classes that work with user-defined data types that have attributes.
For a list of all members of this type, see TDBObject members.

Unit
MemData

Syntax
TDBObject = class(TSharedObject);Remarks
TDBObject is a base class for classes that work with user-defined data types that haveattributes.

© 2019 Devart

548

SQL Server Data Access Components

Inheritance Hierarchy
TSharedObject
TDBObject© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.4.1 Members

TDBObject class overview.

Properties
Name

Description
Used to return the count ofreference to a
TSharedObject object.

RefCount (inherited from TSharedObject)

Methods
Name

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Decrements the reference
count.

AddRef (inherited from TSharedObject)

Release (inherited from TSharedObject)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.5 TMemData Class

Implements storing data in memory.
For a list of all members of this type, see TMemData members.

Unit
MemData

Syntax
TMemData = class(TData);© 2019 DevartReference

549

Inheritance Hierarchy
TData
TMemData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.11.1.5.1 Members

TMemData class overview.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.11.1.6 TObjectType ClassThis class is not used.
For a list of all members of this type, see TObjectType members.

Unit
MemData

SyntaxTObjectType = class(TSharedObject);Inheritance Hierarchy
TSharedObject
TObjectType© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.1 Members

TObjectType class overview.

Properties
Name
AttributeCount© 2019 Devart

Description
Used to indicate the numberof attributes of type.

550

SQL Server Data Access Components

Used to access separate
attributes.
Used to indicate the type ofobject dtObject, dtArray or
dtTable.
Used to return the count ofreference to a
TSharedObject object.
Used to learn the size of an
object instance.

Attributes
DataType
RefCount (inherited from TSharedObject)
Size

Methods
Name

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Indicates whether a
specified Attributecomponent is referenced in
the TAttributes object.
Decrements the reference
count.

AddRef (inherited from TSharedObject)

FindAttribute

Release (inherited from TSharedObject)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.2 Properties

Properties of the TObjectType class.
For a complete list of the TObjectType class members, see the TObjectType Members
topic.

PublicName
AttributeCount
Attributes
DataType

Description
Used to indicate the numberof attributes of type.
Used to access separate
attributes.
Used to indicate the type ofobject dtObject, dtArray or© 2019 DevartReference

551

dtTable.
Used to return the count ofreference to a
TSharedObject object.
Used to learn the size of an
object instance.

RefCount (inherited from TSharedObject)
Size

See Also
TObjectType Class
TObjectType Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.2.1 AttributeCount Property

Used to indicate the number of attributes of type.

Class
TObjectType

Syntaxproperty AttributeCount: Integer;

Remarks
Use the AttributeCount property to determine the number of attributes of type.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.11.1.6.2.2 Attributes Property(Indexer)

Used to access separate attributes.

Class
TObjectType

Syntaxproperty Attributes[Index: integer]: TAttribute;
Parameters© 2019 Devart

Provide Feedback

552

SQL Server Data Access Components

Index
Holds the attribute's ordinal position.

Remarks
Use the Attributes property to access individual attributes. The value of the Index parametercorresponds to the AttributeNo property of TAttribute.

See Also
TAttribute
FindAttribute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.2.3 DataType Property

Used to indicate the type of object dtObject, dtArray or dtTable.

Class
TObjectType

Syntaxproperty DataType: Word;

Remarks
Use the DataType property to determine the type of object dtObject, dtArray or dtTable.

See Also
T:Devart.Dac.Units.MemData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.2.4 Size Property

Used to learn the size of an object instance.

Class
TObjectType

Syntax© 2019 DevartReference553

property Size: Integer;

Remarks
Use the Size property to find out the size of an object instance. Size is a sum of all attribute
sizes.

See Also
TAttribute.Size© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.6.3 Methods

Methods of the TObjectType class.
For a complete list of the TObjectType class members, see the TObjectType Members
topic.

PublicName

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Indicates whether a
specified Attributecomponent is referenced in
the TAttributes object.
Decrements the reference
count.

AddRef (inherited from TSharedObject)

FindAttribute

Release (inherited from TSharedObject)

See Also
TObjectType Class
TObjectType Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

554

SQL Server Data Access Components

5.11.1.6.3.1 FindAttribute Method

Indicates whether a specified Attribute component is referenced in the TAttributes object.

Class
TObjectType

Syntaxfunction FindAttribute(const Name: string): TAttribute; virtual;Parameters
Name
Holds the name of the attribute to search for.
Return Value
TAttribute, if an attribute with a matching name was found. Nil Otherwise.

Remarks
Call FindAttribute to determine if a specified Attribute component is referenced in theTAttributes object. Name is the name of the Attribute for which to search. If FindAttribute finds
an Attribute with a matching name, it returns the TAttribute. Otherwise it returns nil.

See Also
TAttribute
M:Devart.Dac.TObjectType.AttributeByName(System.String)
Attributes© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7 TSharedObject ClassA base class that allows to simplify memory management for object referenced by several
other objects.
For a list of all members of this type, see TSharedObject members.

Unit
MemData

SyntaxTSharedObject = class(System.TObject);© 2019 DevartReference

555

Remarks
TSharedObject allows to simplify memory management for object referenced by several
other objects. TSharedObject holds a count of references to itself. When any object (referer
object) is going to use TSharedObject, it calls the TSharedObject.AddRef method. Referer
object has to call the TSharedObject.Release method after using TSharedObject.

See Also
TBlob
TObjectType© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7.1 Members

TSharedObject class overview.

Properties
Name

Description
Used to return the count ofreference to a
TSharedObject object.

RefCount

Methods
Name

Description
Increments the reference
count for the number ofreferences dependent on theTSharedObject object.
Decrements the reference
count.

AddRefRelease© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7.2 Properties

Properties of the TSharedObject class.
For a complete list of the TSharedObject class members, see the TSharedObject Members
topic.
© 2019 Devart

556

SQL Server Data Access Components

PublicName

Description
Used to return the count ofreference to a
TSharedObject object.

RefCount

See Also
TSharedObject Class
TSharedObject Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7.2.1 RefCount Property

Used to return the count of reference to a TSharedObject object.

Class
TSharedObject

Syntaxproperty RefCount: Integer;

Remarks
Returns the count of reference to a TSharedObject object.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7.3 Methods

Methods of the TSharedObject class.
For a complete list of the TSharedObject class members, see the TSharedObject Members
topic.

PublicName

Description

AddRefIncrements the reference
count for the number of© 2019 DevartReference557

references dependent on theTSharedObject object.
Decrements the reference
count.

ReleaseSee Also
TSharedObject Class
TSharedObject Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.1.7.3.1 AddRef Method

Increments the reference count for the number of references dependent on theTSharedObject object.

Class
TSharedObject

Syntax
procedure AddRef;

Remarks
Increments the reference count for the number of references dependent on theTSharedObject object.

See Also
Release© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.11.1.7.3.2 Release Method

Decrements the reference count.

Class
TSharedObject© 2019 Devart

DAC Forum

Provide Feedback

558

SQL Server Data Access Components

Syntax
procedure Release;

Remarks
Call the Release method to decrement the reference count. When RefCount is 1,
TSharedObject is deleted from memory.

See Also
AddRef© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.2 Types
Types in the MemData unit.

Types
Name

Description
Represents the set of
TLocateExOption.
Represents the set of
TUpdateRecKind.

TLocateExOptions
TUpdateRecKinds© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.2.1 TLocateExOptions Set

Represents the set of TLocateExOption.

Unit
MemData

Syntax
TLocateExOptions = set of TLocateExOption;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference559

5.11.2.2 TUpdateRecKinds Set

Represents the set of TUpdateRecKind.

Unit
MemData

SyntaxTUpdateRecKinds = set of TUpdateRecKind;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.11.3 Enumerations
Enumerations in the MemData unit.

Enumerations
Name

Description
Specifies when the values
should be compressed andthe way they should be
stored.
Specifies the cause of theconnection loss.
Specifies the format ofstoring and representing of
the NUMERIC (DECIMAL)
fields.
Allows to set additional
search parameters which
will be used by the LocateEx
method.
Specifies a sort type forstring fields.
Indicates records for which
the ApplyUpdates method
will be performed.

TCompressBlobMode

TConnLostCause

TDANumericType

TLocateExOption

TSortType
TUpdateRecKind© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

560

SQL Server Data Access Components

5.11.3.1 TCompressBlobMode Enumeration

Specifies when the values should be compressed and the way they should be stored.

Unit
MemData

SyntaxTCompressBlobMode = (cbNone, cbClient, cbServer, cbClientServer);ValuesValue

cbClient

cbClientServer

cbNonecbServer© 1997-2019
Devart. All Rights
Reserved.

Meaning
Values are compressed and stored as compressed data at theclient side. Before posting data to the server decompression is
performed and data at the server side stored in the original form.
Allows to reduce used client memory due to increase accesstime to field values. The time spent on the opening DataSet andexecuting Post increases.
Values are compressed and stored in compressed form. Allows
to decrease the volume of used memory at client and serversides. Access time to the field values increases as for cbClient.
The time spent on opening DataSet and executing Post
decreases.Note: On using cbServer or cbClientServer data on
the server is stored as compressed. Other applications can add
records in uncompressed format but can't read and write alreadycompressed data. If compressed BLOB is partially changed byanother application (if signature was not changed), DAC willconsider its value as NULL.Blob compression is not applied toMemo fields because of possible cutting.
Values not compressed. The default value.
Values are compressed before passing to the server and store at
the server in compressed form. Allows to decrease databasesize on the server. Access time to the field values does notchange. The time spent on opening DataSet and executing Post
usually decreases.
Request Support

DAC Forum

Provide Feedback© 2019 DevartReference561

5.11.3.2 TConnLostCause Enumeration

Specifies the cause of the connection loss.

Unit
MemData

SyntaxTConnLostCause = (clUnknown, clExecute, clOpen, clRefresh, clApply,
clServiceQuery, clTransStart, clConnectionApply, clConnect);

ValuesValue

Meaning
Connection loss detected during DataSet.ApplyUpdates
clApply(Reconnect/Reexecute possible).
Connection loss detected during connection establishingclConnect(Reconnect possible).
clConnectionApply Connection loss detected during Connection.ApplyUpdates(Reconnect/Reexecute possible).
Connection loss detected during SQL execution (Reconnect with
clExecuteexception is possible).
Connection loss detected during execution of a SELECT
clOpenstatement (Reconnect with exception possible).
Connection loss detected during query opening (Reconnect/
clRefresh
Reexecute possible).
Connection loss detected during service information request
clServiceQuery(Reconnect/Reexecute possible).
Connection loss detected during transaction start (Reconnect/
clTransStart
Reexecute possible). clTransStart has less priority thenclConnectionApply.
clUnknown
The connection loss reason is unknown.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
5.11.3.3 TDANumericType Enumeration

Specifies the format of storing and representing of the NUMERIC (DECIMAL) fields.

Unit
MemData© 2019 Devart

562

SQL Server Data Access Components

SyntaxTDANumericType = (ntFloat, ntBCD, ntFmtBCD);

ValuesValue
ntBCD
ntFloat
ntFmtBCD© 1997-2019
Devart. All Rights
Reserved.

Meaning
Data is stored on the client side as currency and represented as
TBCDField. This format allows storing data with precision up to
0,0001.
Data stored on the client side is in double format andrepresented as TFloatField. The default value.
Data is represented as TFMTBCDField. TFMTBCDField gives
greater precision and accuracy than TBCDField, but it is slower.
Request Support

DAC Forum

Provide Feedback

5.11.3.4 TLocateExOption Enumeration

Allows to set additional search parameters which will be used by the LocateEx method.

Unit
MemData

Syntax
TLocateExOption = (lxCaseInsensitive, lxPartialKey, lxNearest,lxNext, lxUp, lxPartialCompare);ValuesValuelxNextMeaning
Similar to loCaseInsensitive. Key fields and key values arematched without regard to the case.
LocateEx moves the cursor to a specific record in a dataset or to
the first record in the dataset that is greater than the values
specified in the KeyValues parameter. For this option to work
correctly dataset should be sorted by the fields the search is
performed in. If dataset is not sorted, the function may return aline that is not connected with the search condition.
LocateEx searches from the current record.

lxPartialCompare

Similar to lxPartialKey, but the difference is that it can process

lxCaseInsensitivelxNearest© 2019 DevartReferencelxPartialKey
lxUp© 1997-2019
Devart. All Rights
Reserved.

563

value entries in any position. For example, 'HAM' would match
both 'HAMM', 'HAMMER.', and also 'MR HAMMER'.
Similar to loPartialKey. Key values can include only a part of thematching key field value. For example, 'HAM' would match both
'HAMM' and 'HAMMER.', but not 'MR HAMMER'.
LocateEx searches from the current record to the first record.
Request Support

DAC Forum

Provide Feedback

5.11.3.5 TSortType Enumeration

Specifies a sort type for string fields.

Unit
MemData

SyntaxTSortType = (stCaseSensitive, stCaseInsensitive, stBinary);

ValuesValue
stBinary
stCaseInsensitive
stCaseSensitive© 1997-2019
Devart. All Rights
Reserved.

Meaning
Sorting by character ordinal values (this comparison is also casesensitive).
Sorting without case sensitivity.
Sorting with case sensitivity.
Request Support

DAC Forum

Provide Feedback

5.11.3.6 TUpdateRecKind Enumeration

Indicates records for which the ApplyUpdates method will be performed.

Unit
MemData

SyntaxTUpdateRecKind = (ukUpdate, ukInsert, ukDelete);© 2019 Devart

564

SQL Server Data Access Components

ValuesValue
ukDeleteukInsert
ukUpdate© 1997-2019
Devart. All Rights
Reserved.

5.12

Meaning
ApplyUpdates will be performed for deleted records.
ApplyUpdates will be performed for inserted records.
ApplyUpdates will be performed for updated records.
Request Support

DAC Forum

Provide Feedback

MemDS
This unit contains implementation of the TMemDataSet class.

ClassesName

Description
A base class for working
with data and manipulating
data in memory.

TMemDataSet

Variables
Name

Description
An exception will be raised if
the value of theUpdateAction parameter is
uaFail.
The DataSetChange event
is sent after a dataset gets
open. It was necessary to fix
a problem with disappeared
vertical scrollbar in some
types of DB-aware grids.

DoNotRaiseExcetionOnUaFail

SendDataSetChangeEventAfterOpen© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1 Classes
Classes in the MemDS unit.

Classes© 2019 DevartReference

Name

Description
A base class for working
with data and manipulating
data in memory.

TMemDataSet© 1997-2019
Devart. All Rights
Reserved.

565

Request Support

DAC Forum

Provide Feedback

5.12.1.1 TMemDataSet ClassA base class for working with data and manipulating data in memory.
For a list of all members of this type, see TMemDataSet members.

Unit
MemDS

Syntax
TMemDataSet = class(TDataSet);

Remarks
TMemDataSet derives from the TDataSet database-engine independent set of properties,
events, and methods for working with data and introduces additional techniques to store andmanipulate data in memory.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.1 Members

TMemDataSet class overview.

Properties
Name
CachedUpdates

IndexFieldNames
KeyExclusive© 2019 Devart

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for a

566

SQL Server Data Access Components

LocalConstraints

LocalUpdate

PreparedRangedUpdateRecordTypes

UpdatesPending

range.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange
ApplyUpdates

CancelRange

CancelUpdates

CommitUpdates
DeferredPost
EditRangeEnd

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.

© 2019 DevartReference

EditRangeStart

GetBlob

LocateLocateEx

PrepareRestoreUpdates

RevertRecord

SaveToXML

SetRange

SetRangeEnd

SetRangeStart© 2019 Devart

567

Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.

568

SQL Server Data Access Components

Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

UnPrepare

UpdateResult

UpdateStatus

EventsName

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.

OnUpdateError

OnUpdateRecord© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2 Properties

Properties of the TMemDataSet class.
For a complete list of the TMemDataSet class members, see the TMemDataSet Members
topic.

PublicName
CachedUpdates

IndexFieldNames

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.

© 2019 DevartReference

569

Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

KeyExclusive

LocalConstraints

LocalUpdate

PreparedRangedUpdateRecordTypes

UpdatesPending

See Also
TMemDataSet Class
TMemDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.1 CachedUpdates Property

Used to enable or disable the use of cached updates for a dataset.

Class
TMemDataSet

Syntaxproperty CachedUpdates: boolean default False;

Remarks
Use the CachedUpdates property to enable or disable the use of cached updates for a© 2019 Devart

570

SQL Server Data Access Components

dataset. Setting CachedUpdates to True enables updates to a dataset (such as postingchanges, inserting new records, or deleting records) to be stored in an internal cache on theclient side instead of being written directly to the dataset's underlying database tables. Whenchanges are completed, an application writes all cached changes to the database in thecontext of a single transaction.
Cached updates are especially useful for client applications working with remote databaseservers. Enabling cached updates brings up the following benefits:
Fewer transactions and shorter transaction times.
Minimized network traffic.
The potential drawbacks of enabling cached updates are:
Other applications can access and change the actual data on the server while users are
editing local copies of data, resulting in an update conflict when cached updates are applied
to the database.
Other applications cannot access data changes made by an application until its cachedupdates are applied to the database.
The default value is False.
Note: When establishing master/detail relationship the CachedUpdates property of detaildataset works properly only when TDADataSetOptions.LocalMasterDetail is set to True.

See Also
UpdatesPending
TMemDataSet.ApplyUpdates
RestoreUpdates
CommitUpdates
CancelUpdates
UpdateStatus
TCustomDADataSet.Options© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.2 IndexFieldNames Property

Used to get or set the list of fields on which the recordset is sorted.

Class
TMemDataSet

Syntax© 2019 DevartReference571

property IndexFieldNames: string;

Remarks
Use the IndexFieldNames property to get or set the list of fields on which the recordset issorted. Specify the name of each column in IndexFieldNames to use as an index for a table.
Ordering of column names is significant. Separate names with semicolon. The specified
columns don't need to be indexed. Set IndexFieldNames to an empty string to reset therecordset to the sort order originally used when the recordset's data was first retrieved.
Each field may optionally be followed by the keyword ASC / DESC or CIS / CS / BIN.
Use ASC, DESC keywords to specify a sort direction for the field. If one of these keywords is
not used, the default sort direction for the field is ascending.
Use CIS, CS or BIN keywords to specify a sort type for string fields:
CIS - compare without case sensitivity;
CS - compare with case sensitivity;
BIN - compare by character ordinal values (this comparison is also case sensitive).
If a dataset uses a TCustomDAConnection component, the default value of sort type depends
on the TCustomDAConnection.Options option of the connection. If a dataset does not use aconnection (TVirtualTable dataset), the default is CS.
Read IndexFieldNames to determine the field (or fields) on which the recordset is sorted.
Ordering is processed locally.
Note: You cannot process ordering by BLOB fields.

ExampleThe following procedure illustrates how to set IndexFieldNames in response to a button click:
DataSet1.IndexFieldNames := 'LastName ASC CIS; DateDue DESC';© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.12.1.1.2.3 KeyExclusive Property

Specifies the upper and lower boundaries for a range.

Class
TMemDataSet

Syntaxproperty KeyExclusive: Boolean;© 2019 Devart

Provide Feedback

572

SQL Server Data Access Components

Remarks
Use KeyExclusive to specify whether a range includes or excludes the records that match its
specified starting and ending values.
By default, KeyExclusive is False, meaning that matching values are included.
To restrict a range to those records that are greater than the specified starting value and lessthan the specified ending value, set KeyExclusive to True.

See Also
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.4 LocalConstraints Property

Used to avoid setting the Required property of a TField component for NOT NULL fields at thetime of opening TMemDataSet.

Class
TMemDataSet

Syntaxproperty LocalConstraints: boolean default True;

Remarks
Use the LocalConstraints property to avoid setting the Required property of a TField
component for NOT NULL fields at the time of opening TMemDataSet. When LocalConstrainsis True, TMemDataSet ignores NOT NULL server constraints. It is useful for tables that havefields updated by triggers.
LocalConstraints is obsolete, and is only included for backward compatibility.
The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference573

5.12.1.1.2.5 LocalUpdate Property

Used to prevent implicit update of rows on database server.

Class
TMemDataSet

Syntaxproperty LocalUpdate: boolean default False;

Remarks
Set the LocalUpdate property to True to prevent implicit update of rows on database server.
Data changes are cached locally in client memory.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.6 Prepared Property

Determines whether a query is prepared for execution or not.

Class
TMemDataSet

Syntaxproperty Prepared: boolean;

Remarks
Check the Prepared property to determine if a query is already prepared for execution.
Prepared is True if the query has already been prepared. While queries don't need to beprepared before execution, performance is often boosted if queries are prepared beforehand,particularly if there are parameterized queries that are executed more than once using thesame parameter values.

See Also
Prepare© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

574

SQL Server Data Access Components

5.12.1.1.2.7 Ranged Property

Indicates whether a range is applied to a dataset.

Class
TMemDataSet

Syntaxproperty Ranged: Boolean;

Remarks
Use the Ranged property to detect whether a range is applied to a dataset.

See Also
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.8 UpdateRecordTypes Property

Used to indicate the update status for the current record when cached updates are enabled.

Class
TMemDataSet

Syntaxproperty UpdateRecordTypes: TUpdateRecordTypes default[rtModified, rtInserted, rtUnmodified];

Remarks
Use the UpdateRecordTypes property to determine the update status for the current record
when cached updates are enabled. Update status can change frequently as records areedited, inserted, or deleted. UpdateRecordTypes offers a convenient method for applications
to assess the current status before undertaking or completing operations that depend on the
update status of records.

See Also© 2019 DevartReference

575

CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.2.9 UpdatesPending Property

Used to check the status of the cached updates buffer.

Class
TMemDataSet

Syntaxproperty UpdatesPending: boolean;

Remarks
Use the UpdatesPending property to check the status of the cached updates buffer. If
UpdatesPending is True, then there are edited, deleted, or inserted records remaining in local
cache and not yet applied to the database. If UpdatesPending is False, there are no suchrecords in the cache.

See Also
CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3 Methods

Methods of the TMemDataSet class.
For a complete list of the TMemDataSet class members, see the TMemDataSet Members
topic.

PublicName
ApplyRange
ApplyUpdates
CancelRange© 2019 Devart

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges

576

SQL Server Data Access Components

CancelUpdates

CommitUpdates
DeferredPost
EditRangeEnd

EditRangeStart

GetBlob

LocateLocateEx

PrepareRestoreUpdates

RevertRecord

SaveToXML

currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO© 2019 DevartReference

577

format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

SetRange

SetRangeEnd

SetRangeStart

UnPrepare

UpdateResult

UpdateStatus

See Also
TMemDataSet Class
TMemDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.12.1.1.3.1 ApplyRange Method

Applies a range to the dataset.

Class
TMemDataSet

Syntax© 2019 Devart

DAC Forum

Provide Feedback

578

SQL Server Data Access Components

procedure ApplyRange;

Remarks
Call ApplyRange to cause a range established with SetRangeStart and SetRangeEnd, or
EditRangeStart and EditRangeEnd, to take effect.
When a range is in effect, only those records that fall within the range are available to theapplication for viewing and editing.
After a call to ApplyRange, the cursor is left on the first record in the range.

See Also
CancelRange
EditRangeEnd
EditRangeStart
IndexFieldNames
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.2 ApplyUpdates Method

Writes dataset's pending cached updates to a database.

Class
TMemDataSet

Overload List
Name
ApplyUpdates
ApplyUpdates(const UpdateRecKinds:
TUpdateRecKinds)© 1997-2019
Request Support
Devart. All Rights
Reserved.

Description
Writes dataset's pending cached updates
to a database.
Writes dataset's pending cached updatesof specified records to a database.
DAC Forum

Provide Feedback© 2019 DevartReference579

Writes dataset's pending cached updates to a database.

Class
TMemDataSet

Syntax
procedure ApplyUpdates; overload; virtual;

Remarks
Call the ApplyUpdates method to write a dataset's pending cached updates to a database.
This method passes cached data to the database, but the changes are not committed to the
database if there is an active transaction. An application must explicitly call the database
component's Commit method to commit the changes to the database if the write is
successful, or call the database's Rollback method to undo the changes if there is an error.
Following a successful write to the database, and following a successful call to aconnection's Commit method, an application should call the CommitUpdates method to clear
the cached update buffer.
Note: The preferred method for updating datasets is to call a connection component's
ApplyUpdates method rather than to call each individual dataset's ApplyUpdates method. The
connection component's ApplyUpdates method takes care of committing and rolling backtransactions and clearing the cache when the operation is successful.

ExampleThe following procedure illustrates how to apply a dataset's cached updates to a database in
response to a button click:procedure ApplyButtonClick(Sender: TObject);
beginwith MyQuery do
begin
Session.StartTransaction;try... <Modify data>
ApplyUpdates; <try to write the updates to the database>Session.Commit; <on success, commit the changes>
exceptRestoreUpdates; <restore update result for applied records>
Session.Rollback; <on failure, undo the changes>
raise; <raise the exception to prevent a call to CommitUpdates!>end;
CommitUpdates; <on success, clear the cache>
end;
end;

© 2019 Devart

580

SQL Server Data Access Components

See Also
TMemDataSet.CachedUpdates
TMemDataSet.CancelUpdates
TMemDataSet.CommitUpdates
TMemDataSet.UpdateStatus© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Writes dataset's pending cached updates of specified records to a database.

Class
TMemDataSet

Syntax
procedure ApplyUpdates(const UpdateRecKinds: TUpdateRecKinds);
overload; virtual;Parameters
UpdateRecKinds
Indicates records for which the ApplyUpdates method will be performed.

Remarks
Call the ApplyUpdates method to write a dataset's pending cached updates of specified
records to a database. This method passes cached data to the database, but the changes
are not committed to the database if there is an active transaction. An application must
explicitly call the database component's Commit method to commit the changes to the
database if the write is successful, or call the database's Rollback method to undo thechanges if there is an error.
Following a successful write to the database, and following a successful call to aconnection's Commit method, an application should call the CommitUpdates method to clear
the cached update buffer.
Note: The preferred method for updating datasets is to call a connection component's
ApplyUpdates method rather than to call each individual dataset's ApplyUpdates method. The
connection component's ApplyUpdates method takes care of committing and rolling backtransactions and clearing the cache when the operation is successful.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

581

Reserved.
5.12.1.1.3.3 CancelRange Method

Removes any ranges currently in effect for a dataset.

Class
TMemDataSet

Syntax
procedure CancelRange;

Remarks
Call CancelRange to remove a range currently applied to a dataset. Canceling a range
reenables access to all records in the dataset.

See Also
ApplyRange
EditRangeEnd
EditRangeStart
IndexFieldNames
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.4 CancelUpdates Method

Clears all pending cached updates from cache and restores dataset in its prior state.

Class
TMemDataSet

Syntax
procedure CancelUpdates;

Remarks
Call the CancelUpdates method to clear all pending cached updates from cache and restore© 2019 Devart

582

SQL Server Data Access Components

dataset in its prior state.
It restores the dataset to the state it was in when the table was opened, cached updates werelast enabled, or updates were last successfully applied to the database.
When a dataset is closed, or the CachedUpdates property is set to False, CancelUpdates iscalled automatically.

See Also
CachedUpdates
TMemDataSet.ApplyUpdates
UpdateStatus© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.5 CommitUpdates Method

Clears the cached updates buffer.

Class
TMemDataSet

Syntax
procedure CommitUpdates;

Remarks
Call the CommitUpdates method to clear the cached updates buffer after both a successful
call to ApplyUpdates and a database component's Commit method. Clearing the cache after
applying updates ensures that the cache is empty except for records that could not beprocessed and were skipped by the OnUpdateRecord or OnUpdateError event handlers. An
application can attempt to modify the records still in cache.
CommitUpdates also checks wether there are pending updates in dataset. And if there are, itcalls ApplyUpdates.
Record modifications made after a call to CommitUpdates repopulate the cached update
buffer and require a subsequent call to ApplyUpdates to move them to the database.

See Also
CachedUpdates
TMemDataSet.ApplyUpdates
UpdateStatus© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

583

Provide Feedback

5.12.1.1.3.6 DeferredPost Method

Makes permanent changes to the database server.

Class
TMemDataSet

Syntax
procedure DeferredPost;

Remarks
Call DeferredPost to make permanent changes to the database server while retaining dataset
in its state whether it is dsEdit or dsInsert.
Explicit call to the Cancel method after DeferredPost has been applied does not abandon
modifications to a dataset already fixed in database.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.7 EditRangeEnd Method

Enables changing the ending value for an existing range.

Class
TMemDataSet

Syntax
procedure EditRangeEnd;

Remarks
Call EditRangeEnd to change the ending value for an existing range.
To specify an end range value, call FieldByName after calling EditRangeEnd.
After assigning a new ending value, call ApplyRange to activate the modified range.

See Also
ApplyRange© 2019 Devart

584

SQL Server Data Access Components

CancelRange
EditRangeStart
IndexFieldNames
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.8 EditRangeStart Method

Enables changing the starting value for an existing range.

Class
TMemDataSet

Syntax
procedure EditRangeStart;

Remarks
Call EditRangeStart to change the starting value for an existing range.
To specify a start range value, call FieldByName after calling EditRangeStart.
After assigning a new ending value, call ApplyRange to activate the modified range.

See Also
ApplyRange
CancelRange
EditRangeEnd
IndexFieldNames
SetRange
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference585

5.12.1.1.3.9 GetBlob Method

Retrieves TBlob object for a field or current record when only its name or the field itself isknown.

Class
TMemDataSet

Overload List
Name
GetBlob(Field: TField)
GetBlob(const FieldName: string)© 1997-2019
Devart. All Rights
Reserved.

Request Support

Description
Retrieves TBlob object for a field or current
record when the field itself is known.
Retrieves TBlob object for a field or current
record when its name is known.
DAC Forum

Provide Feedback

Retrieves TBlob object for a field or current record when the field itself is known.

Class
TMemDataSet

Syntaxfunction GetBlob(Field: TField): TBlob; overload;
Parameters
Field
Holds an existing TField object.
Return Value
TBlob object that was retrieved.

Remarks
Call the GetBlob method to retrieve TBlob object for a field or current record when only its
name or the field itself is known. FieldName is the name of an existing field. The field shouldhave MEMO or BLOB type.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

586

SQL Server Data Access Components

Retrieves TBlob object for a field or current record when its name is known.

Class
TMemDataSet

Syntaxfunction GetBlob(const FieldName: string): TBlob; overload;
Parameters
FieldName
Holds the name of an existing field.
Return Value
TBlob object that was retrieved.

ExampleMSQuery1.GetBlob('Comment').SaveToFile('Comment.txt');

See Also
TBlob© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.10 Locate Method

Searches a dataset for a specific record and positions the cursor on it.

Class
TMemDataSet

Overload List
Name
Locate(const KeyFields: array of TField;
const KeyValues: variant; Options:TLocateOptions)
Locate(const KeyFields: string; const
KeyValues: variant; Options:TLocateOptions)

Description
Searches a dataset by the specified fields
for a specific record and positions cursor
on it.
Searches a dataset by the fields specified
by name for a specific record and positions
the cursor on it.

© 1997-2019
Devart. All Rights

DAC Forum

Request Support

Provide Feedback© 2019 DevartReference

587

Reserved.
Searches a dataset by the specified fields for a specific record and positions cursor on it.

Class
TMemDataSet

Syntaxfunction Locate(const KeyFields: array of TField; const
KeyValues: variant; Options: TLocateOptions): boolean;
reintroduce; overload;
Parameters
KeyFields
Holds TField objects in which to search.
KeyValues
Holds the variant that specifies the values to match in the key fields.
Options
Holds additional search latitude when searching in string fields.
Return Value
True if it finds a matching record, and makes this record the current one. Otherwise it
returns False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Searches a dataset by the fields specified by name for a specific record and positions the
cursor on it.

Class
TMemDataSet

Syntaxfunction Locate(const KeyFields: string; const KeyValues:
variant; Options: TLocateOptions): boolean; overload; override;
Parameters
KeyFields
Holds a semicolon-delimited list of field names in which to search.
KeyValues
Holds the variant that specifies the values to match in the key fields.
© 2019 Devart

588

SQL Server Data Access Components

Options
Holds additional search latitude when searching in string fields.
Return Value
True if it finds a matching record, and makes this record the current one. Otherwise it
returns False.

Remarks
Call the Locate method to search a dataset for a specific record and position cursor on it.
KeyFields is a string containing a semicolon-delimited list of field names on which to search.
KeyValues is a variant that specifies the values to match in the key fields. If KeyFields lists a
single field, KeyValues specifies the value for that field on the desired record. To specify
multiple search values, pass a variant array as KeyValues, or construct a variant array on the
fly using the VarArrayOf routine. An example is provided below.
Options is a set that optionally specifies additional search latitude when searching in string
fields. If Options contains the loCaseInsensitive setting, then Locate ignores case whenmatching fields. If Options contains the loPartialKey setting, then Locate allows partial-string
matching on strings in KeyValues. If Options is an empty set, or if KeyFields does not include
any string fields, Options is ignored.
Locate returns True if it finds a matching record, and makes this record the current one.
Otherwise it returns False.
The Locate function works faster when dataset is locally sorted on the KeyFields fields. Local
dataset sorting can be set with the TMemDataSet.IndexFieldNames property.

ExampleAn example of specifying multiple search values:
with CustTable do
Locate('Company;Contact;Phone', VarArrayOf(['Sight Diver', 'P',
'408-431-1000']), [loPartialKey]);

See Also
TMemDataSet.IndexFieldNames
TMemDataSet.LocateEx© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.11 LocateEx Method

Excludes features that don't need to be included to the TMemDataSet.Locate method of
TDataSet.

© 2019 DevartReference

589

Class
TMemDataSet

Overload List
Name
Description
LocateEx(const KeyFields: array of
Excludes features that don't need to be
TField; const KeyValues: variant; Options: included to the TMemDataSet.Locate
method of TDataSet by the specified fields.
TLocateExOptions)
LocateEx(const KeyFields: string; const Excludes features that don't need to be
included to the TMemDataSet.Locate
KeyValues: variant; Options:
method of TDataSet by the specified field
TLocateExOptions)names.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
Excludes features that don't need to be included to the TMemDataSet.Locate method of
TDataSet by the specified fields.

Class
TMemDataSet

Syntaxfunction LocateEx(const KeyFields: array of TField; const
KeyValues: variant; Options: TLocateExOptions): boolean; overload;
Parameters
KeyFields
Holds TField objects to search in.
KeyValues
Holds the values of the fields to search for.
Options
Holds additional search parameters which will be used by the LocateEx method.
Return Value
True, if a matching record was found. Otherwise returns False.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

590

SQL Server Data Access Components

Excludes features that don't need to be included to the TMemDataSet.Locate method of
TDataSet by the specified field names.

Class
TMemDataSet

Syntaxfunction LocateEx(const KeyFields: string; const KeyValues:
variant; Options: TLocateExOptions): boolean; overload;
Parameters
KeyFields
Holds the fields to search in.
KeyValues
Holds the values of the fields to search for.
Options
Holds additional search parameters which will be used by the LocateEx method.
Return Value
True, if a matching record was found. Otherwise returns False.

Remarks
Call the LocateEx method when you need some features not to be included to the
TMemDataSet.Locate method of TDataSet.
LocateEx returns True if it finds a matching record, and makes that record the current one.
Otherwise LocateEx returns False.
The LocateEx function works faster when dataset is locally sorted on the KeyFields fields.
Local dataset sorting can be set with the TMemDataSet.IndexFieldNames property.
Note: Please add the MemData unit to the "uses" list to use the TLocalExOption
enumeration.

See Also
TMemDataSet.IndexFieldNames
TMemDataSet.Locate© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference591

5.12.1.1.3.12 Prepare Method

Allocates resources and creates field components for a dataset.

Class
TMemDataSet

Syntax
procedure Prepare; virtual;

Remarks
Call the Prepare method to allocate resources and create field components for a dataset. To
learn whether dataset is prepared or not use the Prepared property.
The UnPrepare method unprepares a query.
Note: When you change the text of a query at runtime, the query is automatically closed andunprepared.

See Also
Prepared
UnPrepare© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.13 RestoreUpdates Method

Marks all records in the cache of updates as unapplied.

Class
TMemDataSet

Syntax
procedure RestoreUpdates;

Remarks
Call the RestoreUpdates method to return the cache of updates to its state before calling
ApplyUpdates. RestoreUpdates marks all records in the cache of updates as unapplied. It isuseful when ApplyUpdates fails.

See Also© 2019 Devart

592

SQL Server Data Access Components

CachedUpdates
TMemDataSet.ApplyUpdates
CancelUpdates
UpdateStatus© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.14 RevertRecord Method

Cancels changes made to the current record when cached updates are enabled.

Class
TMemDataSet

Syntax
procedure RevertRecord;

Remarks
Call the RevertRecord method to undo changes made to the current record when cachedupdates are enabled.

See Also
CachedUpdates
CancelUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.15 SaveToXML Method

Saves the current dataset data to a file or a stream in the XML format compatible with ADO
format.

Class
TMemDataSet

Overload List
Name
SaveToXML(Destination: TStream)

Description
Saves the current dataset data to a stream© 2019 DevartReference

SaveToXML(const FileName: string)© 1997-2019
Devart. All Rights
Reserved.

Request Support593

in the XML format compatible with ADO
format.
Saves the current dataset data to a file in
the XML format compatible with ADO
format.
DAC Forum

Provide Feedback

Saves the current dataset data to a stream in the XML format compatible with ADO format.

Class
TMemDataSet

Syntax
procedure SaveToXML(Destination: TStream); overload;
Parameters
Destination
Holds a TStream object.

Remarks
Call the SaveToXML method to save the current dataset data to a file or a stream in the XML
format compatible with ADO format.
If the destination file already exists, it is overwritten. It remains open from the first call to
SaveToXML until the dataset is closed. This file can be read by other applications while it isopened, but they cannot write to the file.
When saving data to a stream, a TStream object must be created and its position must be
set in a preferable value.

See Also
M:Devart.Dac.TVirtualTable.LoadFromFile(System.String,System.Boolean)
M:Devart.Dac.TVirtualTable.LoadFromStream(Borland.Vcl.TStream,System.Boolean)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Saves the current dataset data to a file in the XML format compatible with ADO format.

Class© 2019 Devart

594

SQL Server Data Access Components

TMemDataSet

Syntax
procedure SaveToXML(const FileName: string); overload;
Parameters
FileName
Holds the name of a destination file.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.16 SetRange Method

Sets the starting and ending values of a range, and applies it.

Class
TMemDataSet

Syntax
procedure SetRange(const StartValues: array of System.TVarRec;
const EndValues: array of System.TVarRec; StartExlusive: Boolean= False; EndExclusive: Boolean = False);
Parameters
StartValues
Indicates the field values that designate the first record in the range. In C++,
StartValues_Size is the index of the last value in the StartValues array.
EndValues
Indicates the field values that designate the last record in the range. In C++,
EndValues_Size is the index of the last value in the EndValues array.
StartExlusive
Iindicates the upper and lower boundaries of the start range.
EndExclusive
Indicates the upper and lower boundaries of the end range.

Remarks
Call SetRange to specify a range and apply it to the dataset. The new range replaces thecurrently specified range, if any.
SetRange combines the functionality of SetRangeStart, SetRangeEnd, and ApplyRange in asingle procedure call. SetRange performs the following functions:© 2019 DevartReference595

1. Puts the dataset into dsSetKey state.
2. Erases any previously specified starting range values and ending range values.
3. Sets the start and end range values.
4. Applies the range to the dataset.
After a call to SetRange, the cursor is left on the first record in the range.
If either StartValues or EndValues has fewer elements than the number of fields in the current
index, then the remaining entries are ignored when performing a search.

See Also
ApplyRange
CancelRange
EditRangeEnd
EditRangeStart
IndexFieldNames
KeyExclusive
SetRangeEnd
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.17 SetRangeEnd Method

Indicates that subsequent assignments to field values specify the end of the range of rows to
include in the dataset.

Class
TMemDataSet

Syntax
procedure SetRangeEnd;

Remarks
Call SetRangeEnd to put the dataset into dsSetKey state, erase any previous end range
values, and set them to NULL.
Subsequent field assignments made with FieldByName specify the actual set of ending
values for a range.
After assigning end-range values, call ApplyRange to activate the modified range.
© 2019 Devart

596

SQL Server Data Access Components

See Also
ApplyRange
CancelRange
EditRangeStart
IndexFieldNames
SetRange
SetRangeStart© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.18 SetRangeStart Method

Indicates that subsequent assignments to field values specify the start of the range of rows to
include in the dataset.

Class
TMemDataSet

Syntax
procedure SetRangeStart;

Remarks
Call SetRangeStart to put the dataset into dsSetKey state, erase any previous start range
values, and set them to NULL.
Subsequent field assignments to FieldByName specify the actual set of starting values for arange.
After assigning start-range values, call ApplyRange to activate the modified range.

See Also
ApplyRange
CancelRange
EditRangeStart
IndexFieldNames
SetRange
SetRangeEnd© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

597

Reserved.
5.12.1.1.3.19 UnPrepare Method

Frees the resources allocated for a previously prepared query on the server and client sides.

Class
TMemDataSet

Syntax
procedure UnPrepare; virtual;

Remarks
Call the UnPrepare method to free the resources allocated for a previously prepared query on
the server and client sides.
Note: When you change the text of a query at runtime, the query is automatically closed andunprepared.

See Also
Prepare© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.20 UpdateResult Method

Reads the status of the latest call to the ApplyUpdates method while cached updates areenabled.

Class
TMemDataSet

Syntaxfunction UpdateResult: TUpdateAction;
Return Valuea value of the TUpdateAction enumeration.

Remarks
Call the UpdateResult method to read the status of the latest call to the ApplyUpdates method
while cached updates are enabled. UpdateResult reflects updates made on the records that© 2019 Devart

598

SQL Server Data Access Components

have been edited, inserted, or deleted.
UpdateResult works on the record by record basis and is applicable to the current record
only.

See Also
CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.3.21 UpdateStatus Method

Indicates the current update status for the dataset when cached updates are enabled.

Class
TMemDataSet

Syntaxfunction UpdateStatus: TUpdateStatus; override;
Return Valuea value of the TUpdateStatus enumeration.

Remarks
Call the UpdateStatus method to determine the current update status for the dataset whencached updates are enabled. Update status can change frequently as records are edited,
inserted, or deleted. UpdateStatus offers a convenient method for applications to assess thecurrent status before undertaking or completing operations that depend on the update statusof the dataset.

See Also
CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.4 Events

Events of the TMemDataSet class.
For a complete list of the TMemDataSet class members, see the TMemDataSet Members
topic.

© 2019 DevartReference

599

PublicName

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.

OnUpdateError

OnUpdateRecord

See Also
TMemDataSet Class
TMemDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.4.1 OnUpdateError Event

Occurs when an exception is generated while cached updates are applied to a database.

Class
TMemDataSet

Syntaxproperty OnUpdateError: TUpdateErrorEvent;Remarks
Write the OnUpdateError event handler to respond to exceptions generated when cachedupdates are applied to a database.
E is a pointer to an EDatabaseError object from which application can extract an error
message and the actual cause of the error condition. The OnUpdateError handler can use
this information to determine how to respond to the error condition.
UpdateKind describes the type of update that generated the error.
UpdateAction indicates the action to take when the OnUpdateError handler exits. On entry into
the handler, UpdateAction is always set to uaFail. If OnUpdateError can handle or correct theerror, set UpdateAction to uaRetry before exiting the error handler.
The error handler can use the TField.OldValue and TField.NewValue properties to evaluateerror conditions and set TField.NewValue to a new value to reapply. In this case, set© 2019 Devart

600

SQL Server Data Access Components

UpdateAction to uaRetry before exiting.
Note: If a call to ApplyUpdates raises an exception and ApplyUpdates is not called within thecontext of a try...except block, an error message is displayed. If the OnUpdateError handler
cannot correct the error condition and leaves UpdateAction set to uaFail, the error message isdisplayed twice. To prevent redisplay, set UpdateAction to uaAbort in the error handler.

See Also
CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.1.1.4.2 OnUpdateRecord Event

Occurs when a single update component can not handle the updates.

Class
TMemDataSet

Syntaxproperty OnUpdateRecord: TUpdateRecordEvent;Remarks
Write the OnUpdateRecord event handler to process updates that cannot be handled by asingle update component, such as implementation of cascading updates, insertions, ordeletions. This handler is also useful for applications that require additional control overparameter substitution in update components.
UpdateKind describes the type of update to perform.
UpdateAction indicates the action taken by the OnUpdateRecord handler before it exits. On
entry into the handler, UpdateAction is always set to uaFail. If OnUpdateRecord is successful,it should set UpdateAction to uaApplied before exiting.

See Also
CachedUpdates© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

601

5.12.2 Variables
Variables in the MemDS unit.

Variables
Name

Description
An exception will be raised if
the value of theUpdateAction parameter is
uaFail.
The DataSetChange event
is sent after a dataset gets
open. It was necessary to fix
a problem with disappeared
vertical scrollbar in some
types of DB-aware grids.

DoNotRaiseExcetionOnUaFail

SendDataSetChangeEventAfterOpen© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.2.1 DoNotRaiseExcetionOnUaFail Variable

An exception will be raised if the value of the UpdateAction parameter is uaFail.

Unit
MemDS

SyntaxDoNotRaiseExcetionOnUaFail: boolean = False;

Remarks
Starting with SDAC 4.20.0.13, if the OnUpdateRecord event handler sets the UpdateAction
parameter to uaFail, an exception is raised. The default value of UpdateAction is uaFail. So,
the exception will be raised when the value of this parameter is left unchanged.
To restore the old behaviour, set DoNotRaiseExcetionOnUaFail to True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.12.2.2 SendDataSetChangeEventAfterOpen Variable

The DataSetChange event is sent after a dataset gets open. It was necessary to fix a problem© 2019 Devart

602

SQL Server Data Access Components

with disappeared vertical scrollbar in some types of DB-aware grids.

Unit
MemDS

Syntax
SendDataSetChangeEventAfterOpen: boolean = True;

Remarks
Starting with SDAC 4.20.0.12, the DataSetChange event is sent after a dataset gets open. It
was necessary to fix a problem with disappeared vertical scrollbar in some types of DBaware grids. This problem appears only under Windows XP when visual styles are enabled.
To disable sending this event, change the value of this variable to False.

© 1997-2019
Devart. All Rights
Reserved.

5.13

Request Support

DAC Forum

Provide Feedback

MSAccess
This unit contains implementation of most public classes of SDAC.

ClassesName
TCustomMSConnection

TCustomMSConnectionOptions

TCustomMSDataSet

TCustomMSStoredProc

TCustomMSTable

Description
A base class defining
functionality for classes
derived from it, andintroducing OLE DB specificproperties.
This class allows setting up
the behaviour of theTCustomMSConnection
class.
A component for defining thefunctionality for the classes
derived from it.
A component used toaccess stored procedures
on a database server.
A base class that defines
functionality for descendantclasses which access data
© 2019 DevartReference

TMSChangeNotification

TMSConnection

TMSConnectionOptions

TMSDataSetOptions

TMSDataSource

TMSEncryptor

TMSFileStream

TMSMetadata

TMSParam

TMSParams

TMSQuery© 2019 Devart

603

in a single table without
writing SQL statements.
A component for keeping
information in local dataset
up-to-date through receiving
notifications.
A component forestablishing connection to
the database server,
providing customized login
support and performing
transaction control.
This class allows setting up
the behaviour of the
TMSConnection class.
This class allows setting up
the behaviour of the
TMSDataSet class.
TMSDataSource provides
an interface between a
SDAC dataset components
and data-aware controls on
a form.
The class that performs
encrypting and decrypting ofdata.
A class for managing
FILESTREAM data using
Win32 API.
A component for obtaining
metainformation about
database objects from theserver.
A class that is used to set
the values of individual
parameters passed with
queries or stored
procedures.
Used to control TMSParamobjects.
A component for executing
queries and operatingrecord sets. It also provides
flexible way to update data.

604

SQL Server Data Access Components

TMSSQL

TMSStoredProc

TMSTable

TMSTableData

TMSUDTField

TMSUpdateSQLTMSXMLField

A component for executing
SQL statements and callingstored procedures on the
database server.
A component for accessing
and executing stored
procedures and functions.
A component for retrieving
and updating data in asingle table without writing
SQL statements.
A component for working
with user-defined table types
in SQL Server 2008.
A field class providing native
access to the CLR Userdefined Types (UDT) fields
of SQL Server.
A component for tuning
update operations for the
DataSet component.
A class providing access to
the SQL Server xml data
type.

Types
Name
TMSChangeNotificationEvent

TMSUpdateExecuteEvent

Description
This type is used for the
TMSChangeNotification.On
Change event.
This type is used for the
TCustomMSDataSet.AfterU
pdateExecute andTCustomMSDataSet.Before
UpdateExecute events.

Enumerations
Name

Description

TIsolationLevel

Specifies the extent to which
all outside transactions
interfere with the subsequent© 2019 DevartReference

605

transactions of the current
connection.
Specifies the parameters forlocking the current record.
Indicates the reason of thenotification.
Indicates the source of
notification.
Indicates if this notification is
generated because ofchange or by subscription.
Enumerates the object types
supported by TMSMetadata.

TMSLockType
TMSNotificationInfo
TMSNotificationSource
TMSNotificationType
TMSObjectType

Variables
Name

Description
In SDAC 4.00.0.4 updatestatements execution was
optimized. This optimization
changed the behaviour ofaffected rows count retrieval
for the tables with triggers.

__UseUpdateOptimization

Constants
Name

Description
Read this constant to get thecurrent version number for
SDAC.

SDACVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1 Classes
Classes in the MSAccess unit.

ClassesName
TCustomMSConnection© 2019 Devart

Description
A base class defining
functionality for classes

606

SQL Server Data Access Components

TCustomMSConnectionOptions

TCustomMSDataSet

TCustomMSStoredProc

TCustomMSTable

TMSChangeNotification

TMSConnection

TMSConnectionOptions

TMSDataSetOptions

TMSDataSource

TMSEncryptor

TMSFileStream

derived from it, andintroducing OLE DB specificproperties.
This class allows setting up
the behaviour of theTCustomMSConnection
class.
A component for defining thefunctionality for the classes
derived from it.
A component used toaccess stored procedures
on a database server.
A base class that defines
functionality for descendantclasses which access data
in a single table without
writing SQL statements.
A component for keeping
information in local dataset
up-to-date through receiving
notifications.
A component forestablishing connection to
the database server,
providing customized login
support and performing
transaction control.
This class allows setting up
the behaviour of the
TMSConnection class.
This class allows setting up
the behaviour of the
TMSDataSet class.
TMSDataSource provides
an interface between a
SDAC dataset components
and data-aware controls on
a form.
The class that performs
encrypting and decrypting ofdata.
A class for managing
FILESTREAM data using
Win32 API.
© 2019 DevartReference

A component for obtaining
metainformation about
database objects from theserver.
A class that is used to set
the values of individual
parameters passed with
queries or stored
procedures.
Used to control TMSParamobjects.
A component for executing
queries and operatingrecord sets. It also provides
flexible way to update data.
A component for executing
SQL statements and callingstored procedures on the
database server.
A component for accessing
and executing stored
procedures and functions.
A component for retrieving
and updating data in asingle table without writing
SQL statements.
A component for working
with user-defined table types
in SQL Server 2008.
A field class providing native
access to the CLR Userdefined Types (UDT) fields
of SQL Server.
A component for tuning
update operations for the
DataSet component.
A class providing access to
the SQL Server xml data
type.

TMSMetadata

TMSParam

TMSParams

TMSQuery

TMSSQL

TMSStoredProc

TMSTable

TMSTableData

TMSUDTField

TMSUpdateSQLTMSXMLField© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

607

Request Support

DAC Forum

Provide Feedback

608

SQL Server Data Access Components

5.13.1.1 TCustomMSConnection ClassA base class defining functionality for classes derived from it, and introducing OLE DB
specific properties.
For a list of all members of this type, see TCustomMSConnection members.

Unit
MSAccess

SyntaxTCustomMSConnection = class(TCustomDAConnection);

Remarks
TCustomMSConnection is a base connection class that defines functionality for classes
derived from it, and introduces OLE DB specific properties. Applications should never use
TCustomMSConnection objects directly. Descendants of TCustomMSConnection, such as
TMSConnection, TMSCompactConnection should be used instead.

Inheritance Hierarchy
TCustomDAConnection
TCustomMSConnection

See Also
TMSConnection
TMSCompactConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.1 Members

TCustomMSConnection class overview.

Properties
Name

Description
Contains the version of
ClientVersion
Microsoft OLE DB Provider
for SQL Server.
ConnectDialog (inherited from TCustomDAConnection) Allows to link a
TCustomConnectDialog© 2019 DevartReference609

component.
Used to specify theConnectString (inherited from TCustomDAConnection) connection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
ConvertEOL (inherited from TCustomDAConnection) breaks in string fields andparameters.
Used to specify the
database name that is a
Database
default source of data for
SQL queries once a
connection is established.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLeveltransactions interfere withsubsequent transactions of
the current connection.
Specifies whether a login
LoginPrompt (inherited from TCustomDAConnection) dialog appears immediately
before opening a newconnection.
Used to specify the
behaviour of a
Options
TCustomMSConnection
object.
Serves to supply a
Password (inherited from TCustomDAConnection)
password for login.
Enables or disables using
Pooling (inherited from TCustomDAConnection)connection pool.
PoolingOptions (inherited fromSpecifies the behaviour ofTCustomDAConnection)connection pool.

Server (inherited from TCustomDAConnection)

Serves to supply the server
name for login.
Contains the exact numberof the SQL Server version.
Used to supply a user namefor login.

ServerVersion
Username (inherited from TCustomDAConnection)

Methods© 2019 Devart

610

SQL Server Data Access Components

Name

Description
ApplyUpdates (inherited from TCustomDAConnection) Overloaded. Applies
changes in datasets.
Shares databaseconnection between the
AssignConnect
TCustomMSConnection
components.
Commit (inherited from TCustomDAConnection)
Commits current transaction.
Connect (inherited from TCustomDAConnection)

CreateSQL
Disconnect (inherited from TCustomDAConnection)
ExecProc (inherited from TCustomDAConnection)

ExecProcEx (inherited from TCustomDAConnection)
ExecSQL (inherited from TCustomDAConnection)

ExecSQLEx (inherited from TCustomDAConnection)
GetDatabaseNames (inherited fromTCustomDAConnection)
GetKeyFieldNames (inherited fromTCustomDAConnection)
GetStoredProcNames (inherited fromTCustomDAConnection)
GetTableNames (inherited fromTCustomDAConnection)
MonitorMessage (inherited fromTCustomDAConnection)

Establishes a connection to
the server.
Returns a new instance of
the TMSSQL class andassociates it with thisconnection object.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.
Provides a list of available
key field names.
Returns a list of stored
procedures from the server.
Provides a list of available
tables names.
Sends a specified message
through theTCustomDASQLMonitor
component.

© 2019 DevartReference

OpenDatasets
Ping (inherited from TCustomDAConnection)
RemoveFromPool (inherited fromTCustomDAConnection)
Rollback (inherited from TCustomDAConnection)
StartTransaction (inherited from611

Opens several datasets as
one batch.
Used to check state ofconnection to the server.
Marks the connection thatshould not be returned to thepool after disconnect.
Discards all current datachanges and ends
transaction.
Begins a new usertransaction.

TCustomDAConnection)

EventsName
OnConnectionLost (inherited from

Description
This event occurs whenconnection was lost.

TCustomDAConnection)
OnError (inherited from TCustomDAConnection)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

This event occurs when anerror has arisen in theconnection.
Provide Feedback

5.13.1.1.2 Properties

Properties of the TCustomMSConnection class.
For a complete list of the TCustomMSConnection class members, see theTCustomMSConnection Members topic.

PublicName

Description
Contains the version of
ClientVersion
Microsoft OLE DB Provider
for SQL Server.
Allows to link a
ConnectDialog (inherited from TCustomDAConnection) TCustomConnectDialog
component.
ConnectString (inherited from TCustomDAConnection) Used to specify the© 2019 Devart

612

SQL Server Data Access Components

connection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
ConvertEOL (inherited from TCustomDAConnection) breaks in string fields andparameters.
Used to specify the
database name that is a
Database
default source of data for
SQL queries once a
connection is established.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLeveltransactions interfere withsubsequent transactions of
the current connection.
Specifies whether a login
LoginPrompt (inherited from TCustomDAConnection) dialog appears immediately
before opening a newconnection.
Used to specify the
behaviour of a
Options
TCustomMSConnection
object.
Serves to supply a
Password (inherited from TCustomDAConnection)
password for login.
Enables or disables using
Pooling (inherited from TCustomDAConnection)connection pool.
PoolingOptions (inherited fromSpecifies the behaviour ofTCustomDAConnection)connection pool.

Server (inherited from TCustomDAConnection)

Serves to supply the server
name for login.
Contains the exact numberof the SQL Server version.
Used to supply a user namefor login.

ServerVersion
Username (inherited from TCustomDAConnection)

See Also
TCustomMSConnection Class
TCustomMSConnection Class Members© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

613

Provide Feedback

5.13.1.1.2.1 ClientVersion Property

Contains the version of Microsoft OLE DB Provider for SQL Server.

Class
TCustomMSConnection

Syntaxproperty ClientVersion: string;

Remarks
The version of Microsoft OLE DB Provider for SQL Server (sqloledb.dll).
To get the value of this property, connection to the server must be established.

See Also
TCustomDAConnection.Connect
ServerVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.2.2 Database Property

Used to specify the database name that is a default source of data for SQL queries once a
connection is established.

Class
TCustomMSConnection

Syntaxproperty Database: string;

Remarks
Use the Database property to specify the database name that is a default source of data for
SQL queries once a connection is established.
Altering the Database property makes new database name take effect immediately.

© 2019 Devart

614

SQL Server Data Access Components

When Database is not assigned, SDAC 4.20 and higher will use the default database for thecurrent SQL Server login specified in the TCustomDAConnection.Username property.
Preceding SDAC versions use the 'master' database by default.
Setting Database='Northwind' allows you to omit database specifier in the SELECT
statements. That is, instead of
SELECT * FROM Northwind..Products;
you may just write
SELECT * FROM Products

See Also
TCustomDAConnection.Server
TCustomDAConnection.Username
TCustomDAConnection.Password© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.2.3 IsolationLevel Property

Used to specify the extent to which all outside transactions interfere with subsequenttransactions of the current connection.

Class
TCustomMSConnection

Syntaxproperty IsolationLevel: TIsolationLevel default ilReadCommitted;

Remarks
Use the IsolationLevel property to specify the extent to which all outside transactions interferewith subsequent transactions of the current connection.
Changes to IsolationLevel take effect at a time of starting new transaction or opening newconnection.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference615

5.13.1.1.2.4 Options Property

Used to specify the behaviour of a TCustomMSConnection object.

Class
TCustomMSConnection

Syntaxproperty Options: TCustomMSConnectionOptions;Remarks
Set the properties of Options to specify the behaviour of a TCustomMSConnection object.
Descriptions of all options are in the table below.

Option Name

Description
Specifies if data should be encrypted
before sending it over the network.
Specifies the format of storing andrepresenting the NUMERIC (DECIMAL)
fields for all TCustomMSDataSets
associated with the given connection.
Used to specify a provider from the list of
supported providers.
Causes Microsoft SQL Server to follow theSQL-92 rules regarding quotation markdelimiting identifiers and literal strings.
Used to manage field type creation for the
NTEXT data type.

Encrypt

NumericType

ProviderQuotedIdentifier
UseWideMemos© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.13.1.1.2.5 ServerVersion Property

Contains the exact number of the SQL Server version.

Class
TCustomMSConnection

Syntaxproperty ServerVersion: string;© 2019 Devart

Provide Feedback

616

SQL Server Data Access Components

Remarks
The version of SQL Server.
To get the value of this property, connection to the server must be established.

See Also
TCustomDAConnection.Connect
ClientVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.3 Methods

Methods of the TCustomMSConnection class.
For a complete list of the TCustomMSConnection class members, see theTCustomMSConnection Members topic.

PublicName

Description
ApplyUpdates (inherited from TCustomDAConnection) Overloaded. Applies
changes in datasets.
Shares databaseconnection between the
AssignConnect
TCustomMSConnection
components.
Commit (inherited from TCustomDAConnection)
Commits current transaction.
Connect (inherited from TCustomDAConnection)

CreateSQL
Disconnect (inherited from TCustomDAConnection)
ExecProc (inherited from TCustomDAConnection)

ExecProcEx (inherited from TCustomDAConnection)
ExecSQL (inherited from TCustomDAConnection)

Establishes a connection to
the server.
Returns a new instance of
the TMSSQL class andassociates it with thisconnection object.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
Executes a SQL statement© 2019 DevartReference

ExecSQLEx (inherited from TCustomDAConnection)
GetDatabaseNames (inherited from617

with parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.

TCustomDAConnection)
GetKeyFieldNames (inherited from

Provides a list of available
key field names.

TCustomDAConnection)
GetStoredProcNames (inherited fromReturns a list of stored
procedures from the server.

TCustomDAConnection)
GetTableNames (inherited from

Provides a list of available
tables names.

TCustomDAConnection)
MonitorMessage (inherited fromTCustomDAConnection)
OpenDatasets
Ping (inherited from TCustomDAConnection)
RemoveFromPool (inherited fromTCustomDAConnection)
Rollback (inherited from TCustomDAConnection)
StartTransaction (inherited from

Sends a specified message
through theTCustomDASQLMonitor
component.
Opens several datasets as
one batch.
Used to check state ofconnection to the server.
Marks the connection thatshould not be returned to thepool after disconnect.
Discards all current datachanges and ends
transaction.
Begins a new usertransaction.

TCustomDAConnection)

See Also
TCustomMSConnection Class
TCustomMSConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

618

SQL Server Data Access Components

5.13.1.1.3.1 AssignConnect Method

Shares database connection between the TCustomMSConnection components.

Class
TCustomMSConnection

Syntax
procedure AssignConnect(Source: TCustomMSConnection);
Parameters
SourcePreconnected TCustomMSConnection component which connection is to be shared withthe current TCustomMSConnection component.

Remarks
Use the AssignConnect method to share database connection between the
TCustomMSConnection components.
AssignConnect assumes that the Source parameter points to a preconnected
TCustomMSConnection component which connection is to be shared with the current
TCustomMSConnection component. Note that AssignConnect doesn't make any references
to the Source TCustomMSConnection component. So before disconnecting parent
TCustomMSConnection component call AssignConnect(Nil) or the Disconnect method for all
assigned connections.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.3.2 CreateSQL Method

Returns a new instance of the TMSSQL class and associates it with this connection object.

Class
TCustomMSConnection

Syntaxfunction CreateSQL: TCustomDASQL; override;
Return Valuea new instance of the TMSSQL class.

Remarks© 2019 DevartReference

619

CreateSQL returns a new instance of the TMSSQL class and associates it with thisconnection object.

See Also
M:Devart.Dac.TCustomDAConnection.CreateDataSet()© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.1.3.3 OpenDatasets Method

Opens several datasets as one batch.

Class
TCustomMSConnection

Syntax
procedure OpenDatasets(const ds: array of TCustomMSDataSet);
Parametersds
an array of datasets that will be opened.

Remarks
Call the OpenDatasets method to open several datasets as one batch. This method cansignificantly increase performance when opening queries through remote connection (e. g.
Internet).
When you execute a query through remote connection, a delay occurs. If you open more than
one query, the time of the delay increases proportionally to the number of opened queries.
The OpenDatasets method puts all SQL queries from the received datasets together andexecutes them as one package. The received results are redistributed to the original dataset.
Note, that when this operation is performed, each one of the opened datasets should return
only one resultset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2 TCustomMSConnectionOptions ClassThis class allows setting up the behaviour of the TCustomMSConnection class.
For a list of all members of this type, see TCustomMSConnectionOptions members.

© 2019 Devart

620

SQL Server Data Access Components

Unit
MSAccess

SyntaxTCustomMSConnectionOptions = class(TDAConnectionOptions);

Inheritance Hierarchy
TDAConnectionOptions
TCustomMSConnectionOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2.1 Members

TCustomMSConnectionOptions class overview.

Properties
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)DefaultSortType (inherited from
TDAConnectionOptions)

DisconnectedMode (inherited from
TDAConnectionOptions)

Encrypt
KeepDesignConnected (inherited from
TDAConnectionOptions)

Description
Specifies whether to allow or
not implicit connection
opening.
Used to determine thedefault type of local sortingfor string fields. It is used
when a sort type is not
specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa
mes property of a dataset.
Used to open a connection
only when needed for
performing a server call andcloses after performing theoperation.
Specifies if data should beencrypted before sending itover the network.
Used to prevent anapplication from establishinga connection at the time of© 2019 DevartReference

621

startup.
If True, theTCustomDAConnection.On
LocalFailover (inherited from TDAConnectionOptions) ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.
Specifies the format ofstoring and representing the
NUMERIC (DECIMAL) fields
NumericTypefor all TCustomMSDataSets
associated with the given
connection.
Used to specify a provider
Providerfrom the list of supported
providers.
Causes Microsoft SQL
Server to follow the SQL-92
QuotedIdentifier
rules regarding quotation
mark delimiting identifiers
and literal strings.
Used to manage field type
UseWideMemoscreation for the NTEXT data
type.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
5.13.1.2.2 Properties

Properties of the TCustomMSConnectionOptions class.
For a complete list of the TCustomMSConnectionOptions class members, see theTCustomMSConnectionOptions Members topic.

PublicName

DefaultSortType (inherited from
TDAConnectionOptions)© 2019 Devart

Description
Used to determine thedefault type of local sortingfor string fields. It is used
when a sort type is not
specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa

622

SQL Server Data Access Components

mes property of a dataset.
Used to open a connection
only when needed for
DisconnectedMode (inherited fromperforming a server call and
TDAConnectionOptions)closes after performing theoperation.
Specifies if data should be
Encrypt
encrypted before sending itover the network.
Used to prevent an
KeepDesignConnected (inherited fromapplication from establishing
TDAConnectionOptions)a connection at the time ofstartup.
If True, theTCustomDAConnection.On
LocalFailover (inherited from TDAConnectionOptions) ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.
Specifies the format ofstoring and representing the
NUMERIC (DECIMAL) fields
NumericTypefor all TCustomMSDataSets
associated with the given
connection.
Used to specify a provider
Providerfrom the list of supported
providers.
Causes Microsoft SQL
Server to follow the SQL-92
QuotedIdentifier
rules regarding quotation
mark delimiting identifiers
and literal strings.
Used to manage field type
UseWideMemoscreation for the NTEXT data
type.

Published
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)

Description
Specifies whether to allow or
not implicit connection
opening.

© 2019 DevartReference623

See Also
TCustomMSConnectionOptions Class
TCustomMSConnectionOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2.2.1 Encrypt Property

Specifies if data should be encrypted before sending it over the network.

Class
TCustomMSConnectionOptions

Syntaxproperty Encrypt: boolean default DefValEncrypt;

Remarks
Use the Encrypt property to specify if data should be encrypted before sending it over the
network. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2.2.2 NumericType Property

Specifies the format of storing and representing the NUMERIC (DECIMAL) fields for all
TCustomMSDataSets associated with the given connection.

Class
TCustomMSConnectionOptions

Syntaxproperty NumericType: TDANumericType default ntFloat;

Remarks
Use the NumericType property to specify the format of storing and representing the NUMERIC(DECIMAL) fields for all TCustomMSDataSets associated with the given connection.

© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

624

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.2.2.3 Provider Property

Used to specify a provider from the list of supported providers.

Class
TCustomMSConnectionOptions

Syntaxproperty Provider: TMSProvider default DefValProvider;

Remarks
Use the Provider property to specify a provider from the list of supported providers.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2.2.4 QuotedIdentifier Property

Causes Microsoft SQL Server to follow the SQL-92 rules regarding quotation mark delimiting
identifiers and literal strings.

Class
TCustomMSConnectionOptions

Syntaxproperty QuotedIdentifier: boolean default True;

Remarks
Causes Microsoft SQL Server to follow the SQL-92 rules regarding quotation mark delimiting
identifiers and literal strings. Identifiers delimited by double quotation marks can be either
Transact-SQL reserved keywords or can contain characters not usually allowed by theTransact-SQL syntax rules for identifiers.
True (the default value):
Identifiers can be delimited by double quotation marks, and literals must be delimited by single
quotation marks.
All strings delimited by double quotation marks are interpreted as object identifiers. Therefore,
quoted identifiers do not have to follow the Transact-SQL rules for identifiers. They can be© 2019 DevartReference625

reserved keywords and can include characters not always allowed in the Transact-SQL
identifiers. Double quotation marks cannot be used to delimit literal string expressions; single
quotation marks must be used to enclose literal strings. If a single quotation mark (') is a partof the literal string, it can be represented by two single quotation marks ("). QuotedIdentifiermust be True when reserved keywords are used for object names in the database.
False (BDE compatibility):
Identifiers cannot be quoted and must follow all Transact-SQL rules for identifiers. Literals canbe delimited by either single or double quotation marks. If a literal string is delimited by double
quotation marks, the string can contain embedded single quotation marks such as
apostrophes.
QuotedIdentifier must be True when creating or manipulating indexes on computed columns
or indexed views. If QuotedIdentifier is False, CREATE, UPDATE, INSERT, and DELETE
statements on tables with indexes on computed columns or indexed views will fail.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.2.2.5 UseWideMemos Property

Used to manage field type creation for the NTEXT data type.

Class
TCustomMSConnectionOptions

Syntaxproperty UseWideMemos: boolean default True;

Remarks
If True (the default value), then TWideMemo fields are created for the NTEXT data type. If
False, TMemo fields are created. This option is available for Delphi 2006 and higher.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3 TCustomMSDataSet Class

A component for defining the functionality for the classes derived from it.
For a list of all members of this type, see TCustomMSDataSet members.

Unit
MSAccess© 2019 Devart

626

SQL Server Data Access Components

SyntaxTCustomMSDataSet = class(TCustomDADataSet);

Remarks
TCustomMSDataSet is a base dataset component that defines the functionality for theclasses derived from it. Applications never use TCustomMSDataSet objects directly. Instead
they use descendants of TCustomMSDataSet, such as TMSQuery, TMSTable andTMSStoredProc, that inherit its dataset-related properties and methods.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet

See Also
TMSQueryTCustomMSTable
TCustomMSStoredProc
Performance of Obtaining Data
Master/Detail Relationships© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.1 Members

TCustomMSDataSet class overview.

Properties
Name
BaseSQL (inherited from TCustomDADataSet)

CachedUpdates (inherited from TMemDataSet)
ChangeNotification

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.
Points to a
TMSChangeNotification© 2019 DevartReference

CommandTimeout

Conditions (inherited from TCustomDADataSet)

Connection

CursorType
DataTypeMap (inherited from TCustomDADataSet)

Debug (inherited from TCustomDADataSet)

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption

FetchAll

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)© 2019 Devart

627

component.
Used to specify the wait time
before terminating theattempt to execute acommand and generating anerror.
Used to add WHERE
conditions to a query
Used to specify aconnection object that will be
used to connect to a datastore.
Cursor types supported by
SQL Server.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen a

628

SQL Server Data Access Components

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

query.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.

© 2019 DevartReference

Options

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)© 2019 Devart

629

Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.

630

SQL Server Data Access Components

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

UniDirectional (inherited from TCustomDADataSet)

UpdateObject

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
AddWhere (inherited from TCustomDADataSet)

ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

Description
Adds condition to the
WHERE clause of SELECT
statement in the SQL
property.
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cached© 2019 DevartReference

631

updates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clausefrom the SQL property and
DeleteWhere (inherited from TCustomDADataSet)
assigns the BaseSQL
property.
Enables changing the
EditRangeEnd (inherited from TMemDataSet)
ending value for an existing
range.
Enables changing the
EditRangeStart (inherited from TMemDataSet)
starting value for an existing
range.
Overloaded. Executes a
Execute (inherited from TCustomDADataSet)
SQL statement on theserver.
Indicates whether SQL
Executing (inherited from TCustomDADataSet)
statement is still being
executed.
Used to learn whether
Fetched (inherited from TCustomDADataSet)
TCustomDADataSet has
already fetched all rows.
Used to learn whether
Fetching (inherited from TCustomDADataSet)
TCustomDADataSet is still
fetching rows.
Used to learn whether
FetchingAll (inherited from TCustomDADataSet)
TCustomDADataSet isfetching all rows to the end.
© 2019 Devart

632

SQL Server Data Access Components

Searches for a record whichcontains specified fieldvalues.
Description is not available
FindMacro (inherited from TCustomDADataSet)at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset that
FindNearest (inherited from TCustomDADataSet)
matches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether a
FindParam
parameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
GetBlob (inherited from TMemDataSet)
current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
TMSFileStream object for
GetFileStreamForField
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
FindKey (inherited from TCustomDADataSet)

TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific record© 2019 DevartReference

LocateEx (inherited from TMemDataSet)

Lock
LockTable
MacroByName (inherited from TCustomDADataSet)
OpenNext
ParamByName
Prepare (inherited from TCustomDADataSet)

RefreshQuick
RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)© 2019 Devart633

and positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clause

634

SQL Server Data Access Components

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)of a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
AfterExecute (inherited from TCustomDADataSet)
AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.

© 2019 DevartReference

BeforeFetch (inherited from TCustomDADataSet)

BeforeUpdateExecute

OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

635

Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.3.2 Properties

Properties of the TCustomMSDataSet class.
For a complete list of the TCustomMSDataSet class members, see theTCustomMSDataSet Members topic.

PublicName
BaseSQL (inherited from TCustomDADataSet)

CachedUpdates (inherited from TMemDataSet)

ChangeNotification

CommandTimeout

Conditions (inherited from TCustomDADataSet)
Connection© 2019 Devart

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.
Points to a
TMSChangeNotification
component.
Used to specify the wait time
before terminating theattempt to execute acommand and generating anerror.
Used to add WHERE
conditions to a query
Used to specify a

636

SQL Server Data Access Components

CursorType
DataTypeMap (inherited from TCustomDADataSet)

Debug (inherited from TCustomDADataSet)

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption

FetchAll

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)

connection object that will be
used to connect to a datastore.
Cursor types supported by
SQL Server.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.

© 2019 DevartReference

IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)© 2019 Devart

637

Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the

638

SQL Server Data Access Components

Params
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record by© 2019 DevartReference

SQLUpdate (inherited from TCustomDADataSet)

UniDirectional (inherited from TCustomDADataSet)

UpdateObject

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

639

calling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

See Also
TCustomMSDataSet Class
TCustomMSDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.1 ChangeNotification Property

Points to a TMSChangeNotification component.

Class
TCustomMSDataSet

Syntaxproperty ChangeNotification: TMSChangeNotification;

Remarks
Points to a TMSChangeNotification component used to handle events related to the server© 2019 Devart

640

SQL Server Data Access Components

side changes.
Note: This property is not available of users of SDAC Standard Edition.

See Also
TMSChangeNotification
Options
Options© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.2 CommandTimeout Property

Used to specify the wait time before terminating the attempt to execute a command andgenerating an error.

Class
TCustomMSDataSet

Syntaxproperty CommandTimeout: integer default 0;

Remarks
The time in seconds to wait for the command to execute.
The default value is 0. The 0 value indicates no limit (an attempt to execute a command will
wait indefinitely).
If a command is successfully executed prior to the expiration of the seconds specified,
CommandTimeout has no effect. Otherwise, the 'Query timeout expired' error is generated by
SQL Server. This error has the DB_E_ABORTLIMITREACHED OLEDB error code.
For more information about OLEDB Errors, refer to http://technet.microsoft.com/en-us/library/
ms171852.aspx
Samples
DelphiMSQuery.CommandTimeout := 5; // wait 5 seconds for the command to execute
MSQuery.SQL.Text := 'long-lasting query';try
MSQuery.Execute;excepton E: EOLEDBError do begin
if E.ErrorCode = DB_E_ABORTLIMITREACHED then // the 'Query timeout expir
ShowMessage(E.Message);© 2019 DevartReference

641

raise;end;
end;
C++Builder
MSQuery->CommandTimeout = 5; // wait 5 seconds for the command to execute
MSQuery->SQL->Text = "long-lasting query";try{
MSQuery->Execute();}catch (EOLEDBError &E){
if (E.ErrorCode == DB_E_ABORTLIMITREACHED) // the 'Query timeout expired'
ShowMessage(E.Message);
throw;}

See Also
TMSConnection.ConnectionTimeout© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.3 Connection Property

Used to specify a connection object that will be used to connect to a data store.

Class
TCustomMSDataSet

Syntaxproperty Connection: TCustomMSConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomMSConnection or its
descendant class objects.
At runtime, set the Connection property to reference an existing TCustomMSConnection
object.

See Also
TCustomMSConnection© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

642

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.3.2.4 CursorType Property

Cursor types supported by SQL Server.

Class
TCustomMSDataSet

Syntaxproperty CursorType: TMSCursorType default ctDefaultResultSet;

Remarks
Depending on the text of the SQL statement cursor type and the value of theTCustomDADataSet.ReadOnly property when Options is True, cursor type can be modified
while opening a dataset. To learn more about implicit conversion of cursors, refer to MSDN .
ctStatic, ctKeyset and ctDynamic cursors are server cursors. So theTCustomDADataSet.FetchRows, FetchAll, TMemDataSet.CachedUpdates properties don't
have any influence on such cursors and only the Options.CursorUpdate option does.
To learn how to choose cursor type, refer to MSDN .
The default value is ctDefaultResultSet.

See Also
Performance of Obtaining Data
Options© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.5 Encryption Property

Used to specify encryption options in a dataset.

Class
TCustomMSDataSet

Syntaxproperty Encryption: TMSEncryption;

Remarks© 2019 DevartReference643

Set the Encryption options for using encryption in a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.6 FetchAll Property

Used to decrease the time of retrieving additional records to the client side when calling
TMemDataSet.Locate and TMemDataSet.LocateEx for the first time.

Class
TCustomMSDataSet

Syntaxproperty FetchAll: boolean default True;

Remarks
When the FetchAll property is False, the first call to the TMemDataSet.Locate and
TMemDataSet.LocateEx methods may take a lot of time to retrieve additional records to theclient side. The default value is True.
Since SDAC 4.20, changing the value of the FetchAll option to True for a dataset open in the
FetchAll=False mode will not lead to closing this dataset. This fill forces all records to befetched to the client.
Note: When setting TCustomMSDataSet.FetchAll = False you should keep in mind that
execution of such queries blocks the current session. In order to avoid blocking OLE DB
creates additional session that causes the following problems:
Each additional session runs outside the transaction context thus theTCustomDAConnection.Commit and TCustomDAConnection.Rollback operations in themain session won't apply changes made in additional sessions. This also concernschanges made by TDataSet.Post.
No transactions can be started if there are underfetched datasets within the connection.
Temporary tables created in one session are not accessible from other sessions therefore
simultaneous using of FetchAll = False and temporary tables is impossible.
When editing compound queries with ORDER BY clause setting FetchAll = False may leadto deadlock during TDataSet.Post.
Important: If there is more than one dataset attached to TMSConnection, setting FetchAll =False even in one of them may lead to the problems described above.
To prevent the TMSConnection object from creating additional connections for datasets thatwork in the FetchAll=False mode, you should enable the© 2019 Devart

644

SQL Server Data Access Components

TMSConnectionOptions.MultipleActiveResultSets option. This option is supported since SQL
Server 2005 with using SQL Native Client as OLE DB provider.

See Also
Performance of Obtaining Data
TMSConnectionOptions.MultipleActiveResultSets
TMSConnectionOptions.Provider© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.7 Options Property

Used to specify the behaviour of a TCustomMSDataSet object.

Class
TCustomMSDataSet

Syntaxproperty Options: TMSDataSetOptions;Remarks
Set the properties of Options to specify the behaviour of a TMSDataSet object.
Descriptions of all options are in the table below.

Option Name
AllFieldsEditable
AutoPrepare
AutoRefresh
AutoRefreshInterval

CheckRowVersion

CursorUpdate

Description
Not supported.
Used to execute automatic
TCustomDADataSet.Prepare on a query
execution.
Used to enable automatic refresh of adataset every AutoRefreshInterval seconds.
Used to define in what time interval inseconds the Refresh or RefreshQuick
method of DataSet is called.
Used to determine whether dataset checks
for rows modifications made by anotheruser on automatic generation of SQL
statement for update or delete data.
Used to specify the way data updates
reflect on database when modifying
dataset by using server cursors ctKeySet© 2019 DevartReference

DefaultValues

DescribeParams

DisableMultipleResults
DMLRefresh
EnableBCD

FullRefresh

HideSystemUniqueFields

LastIdentityValueFunction
LongStrings
NonBlocking
NumberRange
PrepareUpdateSQLQueryIdentity

QueryRecCount

QuoteNames
ReflectChangeNotify© 2019 Devart

645

and ctDynamic.
Used to enable TCustomMSDataSet to fill
the DefaultExpression property of TField
objects by an appropriate value.
Used to specify whether to query
TMSParam properties from the serverwhen executing theTCustomDADataSet.Prepare method.
Used to forbid multiple results usage by acommand.
Used to refresh a record when insertion or
update is performed.
Used to specify whether to treat numericfields as floating-point or BCD.
Used to specify the fields to include in theautomatically generated SQL statement
when calling theTCustomDADataSet.RefreshRecord
method.
Used to hide system fields for the prSQL,
prNativeClient and prMSOLEDB providers.
The default value is True.
Determines which system function to use to
obtain an identifier when adding a record.
The default value is vfScopeIdentity.
Represents string fields with the length thatis greater than 255 as TStringField.
Used to fetch rows in a separate thread.
Used to set the MaxValue and MinValue
properties of TIntegerField and TFloatField
to appropriate values.
Used to automatically prepare update
queries before execution.
Used to specify whether to request the
Identity field value on execution of the Insert
or Append method.
Used to perform additional query to getrecord count for this SELECT, so the
RecordCount property reflects the actual
number of records.
Used for TCustomMSDataSet to quote all
field names in autogenerated SQL
statements.
Indicates whether DataSet will be

646

SQL Server Data Access Components

automatically refreshed when the underlying
data on the server is changed.
Used for dataset to locally remove recordon refresh if it does not match filter
condition (WHERE clause for refresh SQL)
anymore.
Used for TCustomMSDataSet to set theRequired property of TField objects for the
NOT NULL fields.
Used to return the new values of fields todataset after insert or update.
Force replace of empty strings with NULL
values in data. Default value is False.
Used for TCustomDADataSet to raise an
exception when the number of updated ordeleted records is not equal 1.
Used to specify whether to discard all
trailing spaces in the fixed-length string
fields of a dataset.
Used to specify whether to discard all
trailing spaces in the variable-length string
fields of a dataset.
Used to specify whether to query additional
keyfields from the server.

RemoveOnRefresh

RequiredFields
ReturnParams
SetEmptyStrToNull
StrictUpdate

TrimFixedChar

TrimVarChar
UniqueRecords© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.8 Params Property

Contains parameters for a query's SQL statement.

Class
TCustomMSDataSet

Syntaxproperty Params: TMSParams stored False;

Remarks
Access Params at runtime to view and set parameter names, values, and data types
dynamically (at design-time use the Parameters editor to set the parameter information).
Params is a zero-based array of parameter records. Index specifies the array element to© 2019 DevartReference

647

access.
An easier way to set and retrieve parameter values, when the name of each parameter isknown, is to call ParamByName.

See Also
TMSParam
ParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.9 SmartFetch Property

The SmartFetch mode is used for fast navigation through a huge amount of records and tominimize memory consumption.

Class
TCustomMSDataSet

Syntaxproperty SmartFetch: TSmartFetchOptions;

See Also
TSmartFetchOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.2.10 UpdateObject Property

Used to point to an update object component which provides SQL statements that perform
updates of read-only datasets.

Class
TCustomMSDataSet

Syntaxproperty UpdateObject: TMSUpdateSQL;

Remarks© 2019 Devart

648

SQL Server Data Access Components

The UpdateObject property points to an update object component which provides SQL
statements that perform updates of read-only datasets when cached updates are enabled.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3 Methods

Methods of the TCustomMSDataSet class.
For a complete list of the TCustomMSDataSet class members, see theTCustomMSDataSet Members topic.

PublicName

Description
Adds condition to the
WHERE clause of SELECT
AddWhere (inherited from TCustomDADataSet)
statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Breaks execution of a SQL
BreakExec (inherited from TCustomDADataSet)
statement on the server.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
© 2019 DevartReference

DeleteWhere (inherited from TCustomDADataSet)

EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

Execute (inherited from TCustomDADataSet)

Executing (inherited from TCustomDADataSet)

Fetched (inherited from TCustomDADataSet)

Fetching (inherited from TCustomDADataSet)

FetchingAll (inherited from TCustomDADataSet)

FindKey (inherited from TCustomDADataSet)
FindMacro (inherited from TCustomDADataSet)

FindNearest (inherited from TCustomDADataSet)

FindParam

GetBlob (inherited from TMemDataSet)© 2019 Devart

649

Removes WHERE clausefrom the SQL property andassigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether aparameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.

650

SQL Server Data Access Components

Returns internal field types
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
TMSFileStream object for
GetFileStreamForField
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
GetDataType (inherited from TCustomDADataSet)

TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock
LockTable
MacroByName (inherited from TCustomDADataSet)
OpenNext
ParamByName
Prepare (inherited from TCustomDADataSet)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, and© 2019 DevartReference

RefreshQuick
RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)© 2019 Devart

651

parses cursor for a query.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.

652

SQL Server Data Access Components

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TCustomMSDataSet Class
TCustomMSDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.1 CreateProcCall Method

Serves for the creating of a stored procedures call.

Class
TCustomMSDataSet

Syntax
procedure CreateProcCall(const Name: string);
Parameters
Name
Holds the name of a stored routine.

Remarks
Using the name of a stored procedure, a command for the call is generated and parameters
are created. After a call to CreateProcCall the values of the parameters should be defined andand the procedure should be executed.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

653

Reserved.
5.13.1.3.3.2 FindParam Method

Indicates whether a parameter with the specified name exists in a dataset.

Class
TCustomMSDataSet

Syntaxfunction FindParam(const Value: string): TMSParam;
Parameters
Value
Holds the name of the parameter to search for.
Return ValueA TMSParam object, if a param with the matching name was found.

Remarks
Call the FindParam method to determine if parameter with the specified name exists in adataset. Name is the name of the param for which to search. If FindParam finds a param withthe matching name, it returns a TMSParam object for the specified Name. Otherwise it
returns nil.

See Also
ParamsParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.3 GetFileStreamForField Method

Used to create the TMSFileStream object for working with FILESTREAM data.

Class
TCustomMSDataSet

Syntaxfunction GetFileStreamForField(const FieldName: string; const
DesiredAccess: TMSSqlFilestreamDesiredAccess = daReadWrite; const© 2019 Devart

654

SQL Server Data Access Components

OpenOptions: TMSSqlFilestreamOpenOptions = []; const
AllocationSize: Int64 = 0): TMSFileStream;
Parameters
FieldName
Contains the existing field name of a VARBINARY(MAX) column.
DesiredAccess
Determines the mode that is used to access FILESTREAM data.
The following values can be used:daRead - data can be read from the file.
daWrite - data can be written to the file.
daReadWrite - data can be read and written from the file.
OpenOptions
Determines file attributes and flags. By default, the file is being opened or created with nospecial options. The following values can be used:
ooAsync - The file is being opened or created for asynchronous I/O.
ooNoBuffering - The system opens the file without system caching.
ooNoWriteThrough - The system does not write through an intermediate cache. Writes go
directly to disk.
ooSequentialScan - The file is being accessed sequentially from beginning to end. The
system can use this as a hint to optimize file caching. If an application moves the file pointerfor random access, optimal caching may not occur.
ooRandomAccess - The file is being accessed randomly. The system can use this as ahint to optimize file caching.
AllocationSize
Determines the initial allocation size of the data file in bytes. It is ignored in read mode. If thisparameter is 0, the default file system behavior is used.
Return ValueThe TMSFileStream object for working with FILESTREAM data.

Remarks
Creates the TMSFileStream object for working with FILESTREAM data of specified column.
Transaction must be started before calling this method.
Note that this method requests server to obtain the Win32 compatible file handle for a
FILESTREAM data.
To obtain the file handle, the following steps are performed:
1. getting the current transaction context of a session by calling the© 2019 DevartReference655

GET_FILESTREAM_TRANSACTION_CONTEXT Transact-SQL function. ( http://
msdn.microsoft.com/en-us/library/bb934014.aspx )2. obtaining the Win32 file handle by executing the OpenSqlFilestream API. ( http://
msdn.microsoft.com/en-us/library/bb933972.aspx )Note: You can find more information about working with FILESTREAM data in MSDN at http://
msdn.microsoft.com/en-us/library/cc949109(v=sql.100).aspx

See Also
TMSFileStream© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.4 Lock Method

Locks the current records to prevent multiple users' access to it.

Class
TCustomMSDataSet

Overload List
Name
Lock
Lock(LockType: TMSLockType)© 1997-2019
Devart. All Rights
Reserved.

Request Support

Description
Locks the current records to prevent
multiple users' access to it.
Locks the current records to prevent
multiple users' access to it.
DAC Forum

Provide Feedback

Locks the current records to prevent multiple users' access to it.

Class
TCustomMSDataSet

Syntax
procedure Lock; overload; override;© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

656

SQL Server Data Access Components

Reserved.
Locks the current records to prevent multiple users' access to it.

Class
TCustomMSDataSet

Syntax
procedure Lock(LockType: TMSLockType); reintroduce; overload;
Parameters
LockType
Holds the lock type.

Remarks
This method locks the current record in dataset to prevent multiple users' access to it.
Record lock can be performed only within a transaction. If an application cannot update/lock arecord because it has already been locked, it will wait until the lock is released. When theserver lock timeout has expired, but lock is not acquired, an exception will be raised. Lock isreleased when the transaction is committed/rolled back.
You should also be aware of the Lock Escalation mechanism of SQL Server using locking in
SDAC. Locking multiple records in the same table may lead to the locking of a whole table.
This will avoid the server's resources overrun.
Note There is an optimization for exclusive locks - SQL Server checks whether data has
been changed since the transaction was started. If not, then a lock request is ignored. For
more information see this topic of MSDN.

ExampleTo avoid this issue, you can refresh only locked record:

if not MSQuery.Connection.InTransaction then// check whether the transac
MSQuery.Connection.StartTransaction;// run the transaction// setup how much time to wait before raising an exception// if the record is already locked by someone else
MSQuery.Connection.ExecSQL('SET LOCK_TIMEOUT ' + IntToStr(StrToInt(edLock
MSQuery.Lock(ltExclusive);// perform exclusive lock
MSQuery.RefreshRecord;// make sure that the record is lockSee Also
TCustomMSDataSet.LockTable
TCustomDAConnection.StartTransaction© 2019 DevartReference

657

TCustomDAConnection.Commit
TCustomDAConnection.Rollback© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.5 LockTable Method

Locks a table to prevent multiple access to it.

Class
TCustomMSDataSet

Syntax
procedure LockTable(LockType: TMSLockType);
Parameters
LockType
Holds the lock type.

Remarks
This method locks the underlying dataset's table to prevent multiple users' access to it.
Table lock can be performed only within a transaction. If an application cannot update/lock atable because it has already been locked, it will wait until the lock is released. When theserver lock timeout has expired, but lock is not acquired, an exception will be raised. Lock isreleased when the transaction is committed/rolled back.

See Also
TCustomMSDataSet.Lock
TCustomDAConnection.StartTransaction
TCustomDAConnection.Commit
TCustomDAConnection.Rollback© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.13.1.3.3.6 OpenNext Method

Opens next rowset in the statement.

Class© 2019 Devart

DAC Forum

Provide Feedback

658

SQL Server Data Access Components

TCustomMSDataSet

Syntaxfunction OpenNext: boolean;
Return Value
True, if DataSet opens.

Remarks
Call the OpenNext method to get the second and other ResultSets while executing a
multiresult query. If DataSet opens, it returns True. If there are no record sets to be
represented, it will return False, and the current record set will be closed. Has effect only forthe ctDefaultResultSet cursor. The OpenNext method isn't compatible with
TCustomDADataSet.Prepare.

ExampleHere is a small piece of code that demonstrates the approach of working with multiple
datasets returned by a multi-statement query:
MSQuery.SQL.Clear;
MSQuery.SQL.Add('SELECT * FROM Table1;');MSQuery.SQL.Add('SELECT * FROM Table2;');
MSQuery.SQL.Add('SELECT * FROM Table3;');MSQuery.SQL.Add('SELECT * FROM Table4;');
MSQuery.SQL.Add('SELECT * FROM Table5;');
MSQuery.FetchAll := False;
MSQuery.Open;
repeat//< do something >until not MSQuery.OpenNext;

See Also
TCustomDADataSet.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.7 ParamByName Method

Provides access to a parameter by its name.

Class
TCustomMSDataSet© 2019 DevartReference

659

Syntaxfunction ParamByName(const Value: string): TMSParam;
Parameters
Value
Holds the name of the parameter to retrieve information for.
Return Valuea TMSParam object.

Remarks
Call the ParamByName method to set or use parameter information for a specific parameterbased on its name. Name is the name of the parameter for which to retrieve information.
ParamByName is used to set a parameter's value at runtime and returns a TMSParamobject.

ExampleThe following statement retrieves the current value of a parameter called "Contact" into anedit box:
Edit1.Text := Query1.ParamsByName('Contact').AsString;See Also
TMSParam
ParamsFindParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.3.8 RefreshQuick Method

An optimized procedure to retrieve the changes applied to the server by other clients to theparticular client side.

Class
TCustomMSDataSet

Syntax
procedure RefreshQuick(const CheckDeleted: boolean);© 2019 Devart

660

SQL Server Data Access Components

Parameters
CheckDeleted
if True, records deleted by other clients will be checked additionally. If False, remote records
are not checked.

Remarks
Call the RefreshQuick method to quickly retrieve to the client side changes applied to theserver by other clients. The main difference between the RefreshQuick and Refresh methods
is that RefreshQuick does not transfer to the client all data like the Refresh method does. The
only rows that were added or modified from the moment of the last refresh are returned to aclient. The necessity of data inquiry for each row is defined by the TIMESTAMP field. So theRefreshQuick method requires query to include a unique key fields and a TIMESTAMP field. If
the CheckDeleted parameter value is True, records deleted by other clients will be checked
additionally.
This method is especially effective for queries with huge data level in the single row.
This feature does not work with SQL Server Compact Edition.
Note: If RefreshQuick is called for a dataset which is ordered on the server (query includes
the ORDER BY clause), dataset records ordering can be violated because not all records will
be retrieved by this method. You can use local ordering to solve this problem. For more
information about local ordering, see the TMemDataSet.IndexFieldNames property
description.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.4 Events

Events of the TCustomMSDataSet class.
For a complete list of the TCustomMSDataSet class members, see theTCustomMSDataSet Members topic.

PublicName
AfterExecute (inherited from TCustomDADataSet)
AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lock© 2019 DevartReference

BeforeFetch (inherited from TCustomDADataSet)

BeforeUpdateExecute

OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)661

and refresh operation.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.

See Also
TCustomMSDataSet Class
TCustomMSDataSet Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.3.4.1 AfterUpdateExecute Event

Occurs after executing insert, delete, update, lock and refresh operation.

Class
TCustomMSDataSet

Syntaxproperty AfterUpdateExecute: TMSUpdateExecuteEvent;Remarks
The AfterUpdateExecute event occurs after executing insert, delete, update, lock and refresh
operation. You can use AfterUpdateExecute to read parameters of corresponding statements.

See Also
BeforeUpdateExecute© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

662

SQL Server Data Access Components

5.13.1.3.4.2 BeforeUpdateExecute Event

Occurs before executing insert, delete, update, lock and refresh operation.

Class
TCustomMSDataSet

Syntaxproperty BeforeUpdateExecute: TMSUpdateExecuteEvent;Remarks
The BeforeUpdateExecute event occurs before executing insert, delete, update, lock andrefresh operation. You can use BeforeUpdateExecute to set parameters of corresponding
statements.

See Also
AfterUpdateExecute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4 TCustomMSStoredProc Class

A component used to access stored procedures on a database server.
For a list of all members of this type, see TCustomMSStoredProc members.

Unit
MSAccess

SyntaxTCustomMSStoredProc = class(TCustomMSDataSet);

Remarks
TCustomMSStoredProc implements functionality to access stored procedures on a databaseserver.
You need only to define the StoredProcName property, while not bothering about writing SQL
statement by hand.
Use the Execute method at runtime to generate a request that instructs server to executeprocedure and return parameters in the Params property.

© 2019 DevartReference

663

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet
TCustomMSStoredProc

See Also
TCustomMSDataSet
TMSStoredProc
Performance of Obtaining Data
Master/Detail Relationships© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4.1 Members

TCustomMSStoredProc class overview.

Properties
Name

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aConnection (inherited from TCustomMSDataSet)
connection object that will be
used to connect to a data
© 2019 Devart

664

SQL Server Data Access Components

CursorType (inherited from TCustomMSDataSet)
DataTypeMap (inherited from TCustomDADataSet)

Debug (inherited from TCustomDADataSet)

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption (inherited from TCustomMSDataSet)

FetchAll (inherited from TCustomMSDataSet)

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)

store.
Cursor types supported by
SQL Server.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.

© 2019 DevartReference

KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)© 2019 Devart

665

Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.

666

SQL Server Data Access Components

Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling the© 2019 DevartReference

SQLUpdate (inherited from TCustomDADataSet)

StoredProcName

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

UpdatingTable

667

TCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used to specify the stored
procedure name that is to becalled on the server.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.
Specifies which table in aquery is assumed to be thetarget for subsequent datamodification queries as aresult of user incentive toinsert, update or delete
records.

Methods
Name
AddWhere (inherited from TCustomDADataSet)

ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)© 2019 Devart

Description
Adds condition to the
WHERE clause of SELECT
statement in the SQL
property.
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.

668

SQL Server Data Access Components

Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clausefrom the SQL property and
DeleteWhere (inherited from TCustomDADataSet)
assigns the BaseSQL
property.
Enables changing the
EditRangeEnd (inherited from TMemDataSet)
ending value for an existing
range.
Enables changing the
EditRangeStart (inherited from TMemDataSet)
starting value for an existing
range.
Executes SQL statements
ExecProcon the server.
Overloaded. Executes a
Execute (inherited from TCustomDADataSet)
SQL statement on theserver.
Indicates whether SQL
Executing (inherited from TCustomDADataSet)
statement is still being
executed.
Used to learn whether
Fetched (inherited from TCustomDADataSet)
TCustomDADataSet has
already fetched all rows.
Used to learn whether
Fetching (inherited from TCustomDADataSet)
TCustomDADataSet is still
fetching rows.
CancelRange (inherited from TMemDataSet)

FetchingAll (inherited from TCustomDADataSet)

Used to learn whether
TCustomDADataSet is© 2019 DevartReference669

fetching all rows to the end.
Searches for a record which
FindKey (inherited from TCustomDADataSet)
contains specified fieldvalues.
Description is not available
FindMacro (inherited from TCustomDADataSet)at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset that
FindNearest (inherited from TCustomDADataSet)
matches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether a
FindParam (inherited from TCustomMSDataSet)
parameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
GetBlob (inherited from TMemDataSet)
current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)
Locate (inherited from TMemDataSet)© 2019 Devart

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches a

670

SQL Server Data Access Components

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)

PrepareSQL

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)
SaveSQL (inherited from TCustomDADataSet)

dataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
Builds a query for
TCustomMSStoredProc
based on the Params andStoredProcName
properties, and assign it to
the SQL property.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property© 2019 DevartReference

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

671

value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName

Description

AfterExecute (inherited from TCustomDADataSet)

Occurs after a component© 2019 Devart

672

SQL Server Data Access Components

AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute (inherited fromTCustomMSDataSet)
BeforeFetch (inherited from TCustomDADataSet)
BeforeUpdateExecute (inherited fromTCustomMSDataSet)
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.4.2 Properties

Properties of the TCustomMSStoredProc class.
For a complete list of the TCustomMSStoredProc class members, see theTCustomMSStoredProc Members topic.

PublicName

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.

© 2019 DevartReference

673

Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
Disconnected (inherited from TCustomDADataSet)
opened after connection isclosed.
Used to specify encryption
Encryption (inherited from TCustomMSDataSet)
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
FetchAll (inherited from TCustomMSDataSet)
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
FetchRows (inherited from TCustomDADataSet)
across the network at thesame time.
Used to change the WHERE
clause of SELECT
FilterSQL (inherited from TCustomDADataSet)
statement and reopen aquery.

© 2019 Devart

674

SQL Server Data Access Components

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
© 2019 DevartReference

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)© 2019 Devart

675

TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used676

SQL Server Data Access Components

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

StoredProcName

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

UpdatingTable

to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used to specify the stored
procedure name that is to becalled on the server.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.
Specifies which table in aquery is assumed to be thetarget for subsequent datamodification queries as aresult of user incentive toinsert, update or delete
records.

See Also
TCustomMSStoredProc Class
TCustomMSStoredProc Class Members© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

677

Provide Feedback

5.13.1.4.2.1 StoredProcName Property

Used to specify the stored procedure name that is to be called on the server.

Class
TCustomMSStoredProc

Syntaxproperty StoredProcName: string;

Remarks
Use the StoredProcName property to specify the name of the stored procedure to call on theserver. If StoredProcName does not match the name of the existing stored procedure on theserver, then when an application attempts to prepare the procedure prior to execution, an
exception is raised.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4.2.2 UpdatingTable Property

Specifies which table in a query is assumed to be the target for subsequent data-modification
queries as a result of user incentive to insert, update or delete records.

Class
TCustomMSStoredProc

Syntaxproperty UpdatingTable: string;

Remarks
Ose the UpdatingTable property on Insert, Update, Delete, or RefreshRecord (see also
TCustomMSDataSet.Options) if appropriate SQL (SQLInsert, SQLUpdate or SQLDelete) is
not provided.
If UpdatingTable is not set then the first table used in query is assumed to be the target.
If a query is addressed to the View then entire View is taken as a target for subsequent© 2019 Devart

678

SQL Server Data Access Components

modifications.
All fields from other than target table have their ReadOnly properties set to True (ifTCustomMSDataSet.Options is True).
With TCustomMSDataSet.CursorType UpdatingTable can be used only if
TCustomMSDataSet.Options = False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4.3 Methods

Methods of the TCustomMSStoredProc class.
For a complete list of the TCustomMSStoredProc class members, see theTCustomMSStoredProc Members topic.

PublicName

Description
Adds condition to the
WHERE clause of SELECT
AddWhere (inherited from TCustomDADataSet)
statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
DeferredPost (inherited from TMemDataSet)
Makes permanent changes© 2019 DevartReference

DeleteWhere (inherited from TCustomDADataSet)

EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)
ExecProc
Execute (inherited from TCustomDADataSet)

Executing (inherited from TCustomDADataSet)

Fetched (inherited from TCustomDADataSet)

Fetching (inherited from TCustomDADataSet)

FetchingAll (inherited from TCustomDADataSet)

FindKey (inherited from TCustomDADataSet)
FindMacro (inherited from TCustomDADataSet)

FindNearest (inherited from TCustomDADataSet)

FindParam (inherited from TCustomMSDataSet)
GetBlob (inherited from TMemDataSet)© 2019 Devart679

to the database server.
Removes WHERE clausefrom the SQL property andassigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Executes SQL statementson the server.
Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether aparameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or

680

SQL Server Data Access Components

current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
© 2019 DevartReference

ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)

PrepareSQL

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)© 2019 Devart

681

Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
Builds a query for
TCustomMSStoredProc
based on the Params andStoredProcName
properties, and assign it to
the SQL property.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequent682

SQL Server Data Access Components

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

assignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TCustomMSStoredProc Class
TCustomMSStoredProc Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4.3.1 ExecProc Method

Executes SQL statements on the server.

Class
TCustomMSStoredProc

Syntax
procedure ExecProc;

Remarks
Call the ExecProc method to execute a SQL statement on the server. If SQL statement is a

© 2019 DevartReference

683

query, ExecProc calls the Open method.
Internally ExecProc calls inherited TCustomDADataSet.Execute method and is only included
for compatibility with BDE.

See Also
TCustomDADataSet.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.4.3.2 PrepareSQL Method

Builds a query for TCustomMSStoredProc based on the Params and StoredProcName
properties, and assign it to the SQL property.

Class
TCustomMSStoredProc

Syntax
procedure PrepareSQL;

Remarks
Call the PrepareSQL method to build a query for TCustomMSStoredProc based on the
Params and StoredProcName properties, and assign it to the SQL property. Generated queryis then verified to be valid and, if necessary, the list of parameters is modified.
PrepareSQL is called implicitly when TCustomMSStoredProc is executed.

See Also
TCustomDADataSet.Params
StoredProcName
ExecProc© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.5 TCustomMSTable ClassA base class that defines functionality for descendant classes which access data in a single
table without writing SQL statements.
For a list of all members of this type, see TCustomMSTable members.

© 2019 Devart

684

SQL Server Data Access Components

Unit
MSAccess

SyntaxTCustomMSTable = class(TCustomMSDataSet);

Remarks
TCustomMSTable implements functionality to access data in a table. Use TCustomMSTable
properties and methods to gain direct access to records and fields in an underlying server
database without writing SQL statements.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet
TCustomMSTable

See Also
TMSTable
TMSStoredProc
Performance of Obtaining Data

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.5.1 Members

TCustomMSTable class overview.

Properties
Name
BaseSQL (inherited from TCustomDADataSet)

CachedUpdates (inherited from TMemDataSet)

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.

© 2019 DevartReference

685

Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
Disconnected (inherited from TCustomDADataSet)
opened after connection isclosed.
Used to specify encryption
Encryption (inherited from TCustomMSDataSet)
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
FetchAll (inherited from TCustomMSDataSet)
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
FetchRows (inherited from TCustomDADataSet)
across the network at thesame time.
FilterSQL (inherited from TCustomDADataSet)
Used to change the WHERE© 2019 Devart

686

SQL Server Data Access Components

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to the© 2019 DevartReference

Options (inherited from TCustomMSDataSet)
OrderFields

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)
SQLInsert (inherited from TCustomDADataSet)© 2019 Devart

687

master one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to build ORDER BY
clause of SQL statements.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL

688

SQL Server Data Access Components

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

TableName

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used to specify the name ofthe database table that thiscomponent encapsulates.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name

Description

AddWhere (inherited from TCustomDADataSet)

Adds condition to the
WHERE clause of SELECT© 2019 DevartReference

689

statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clausefrom the SQL property and
DeleteWhere (inherited from TCustomDADataSet)
assigns the BaseSQL
property.
Enables changing the
EditRangeEnd (inherited from TMemDataSet)
ending value for an existing
range.
Enables changing the
EditRangeStart (inherited from TMemDataSet)
starting value for an existing
range.
Overloaded. Executes a
Execute (inherited from TCustomDADataSet)
SQL statement on theserver.
Indicates whether SQL
Executing (inherited from TCustomDADataSet)
statement is still being
executed.
Used to learn whether
Fetched (inherited from TCustomDADataSet)
TCustomDADataSet has
already fetched all rows.
© 2019 Devart

690

SQL Server Data Access Components

Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
FetchingAll (inherited from TCustomDADataSet)
TCustomDADataSet isfetching all rows to the end.
Searches for a record which
FindKey (inherited from TCustomDADataSet)
contains specified fieldvalues.
Description is not available
FindMacro (inherited from TCustomDADataSet)at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset that
FindNearest (inherited from TCustomDADataSet)
matches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether a
FindParam (inherited from TCustomMSDataSet)
parameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
GetBlob (inherited from TMemDataSet)
current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
Fetching (inherited from TCustomDADataSet)

TCustomDADataSet)

key field names.

GetOrderBy (inherited from TCustomDADataSet)

Retrieves an ORDER BY
clause from a SQL
statement.

© 2019 DevartReference

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)
PrepareSQL

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)© 2019 Devart

691

Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
Determines KeyFields andbuild query ofTCustomMSTable.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates are

692

SQL Server Data Access Components

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

enabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

Events© 2019 DevartReference

Name
AfterExecute (inherited from TCustomDADataSet)
AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute (inherited fromTCustomMSDataSet)
BeforeFetch (inherited from TCustomDADataSet)
BeforeUpdateExecute (inherited fromTCustomMSDataSet)
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

693

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.5.2 Properties

Properties of the TCustomMSTable class.
For a complete list of the TCustomMSTable class members, see the TCustomMSTable
Members topic.

PublicName

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
ChangeNotification (inherited from TCustomMSDataSet) Points to a
TMSChangeNotification© 2019 Devart

694

SQL Server Data Access Components

component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
Disconnected (inherited from TCustomDADataSet)
opened after connection isclosed.
Used to specify encryption
Encryption (inherited from TCustomMSDataSet)
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
FetchAll (inherited from TCustomMSDataSet)
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
FetchRows (inherited from TCustomDADataSet)
across the network at thesame time.
FilterSQL (inherited from TCustomDADataSet)

Used to change the WHERE
clause of SELECT
statement and reopen a© 2019 DevartReference

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)© 2019 Devart

695

query.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.

696

SQL Server Data Access Components

Options (inherited from TCustomMSDataSet)
OrderFields

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to build ORDER BY
clause of SQL statements.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
© 2019 DevartReference

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

TableName

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

697

when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used to specify the name ofthe database table that thiscomponent encapsulates.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

See Also
TCustomMSTable Class
TCustomMSTable Class Members© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

698

SQL Server Data Access Components

Reserved.
5.13.1.5.2.1 OrderFields Property

Used to build ORDER BY clause of SQL statements.

Class
TCustomMSTable

Syntaxproperty OrderFields: string;

Remarks
TCustomMSTable uses the OrderFields property to build ORDER BY clause of SQL
statements.
Place commas to separate fields in a single string.
TCustomMSTable is reopened when the OrderFields property is being changed.

See Also
TCustomMSTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.5.2.2 TableName Property

Used to specify the name of the database table that this component encapsulates.

Class
TCustomMSTable

Syntaxproperty TableName: string;

Remarks
Use the TableName property to specify the name of the database table that this component
encapsulates. At design-time select a valid table name from the TableName drop-down list in
the Object Inspector.
Note: To work with temporary tables you must set TCustomMSDataSet.FetchAll to True (fordetails see the FetchAll description).

© 2019 DevartReference699

See Also
TCustomMSTable
TCustomDAConnection.GetTableNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.5.3 Methods

Methods of the TCustomMSTable class.
For a complete list of the TCustomMSTable class members, see the TCustomMSTable
Members topic.

PublicName

Description
Adds condition to the
WHERE clause of SELECT
AddWhere (inherited from TCustomDADataSet)
statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
© 2019 Devart

700

SQL Server Data Access Components

DeleteWhere (inherited from TCustomDADataSet)

EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

Execute (inherited from TCustomDADataSet)

Executing (inherited from TCustomDADataSet)

Fetched (inherited from TCustomDADataSet)

Fetching (inherited from TCustomDADataSet)

FetchingAll (inherited from TCustomDADataSet)

FindKey (inherited from TCustomDADataSet)
FindMacro (inherited from TCustomDADataSet)

FindNearest (inherited from TCustomDADataSet)

FindParam (inherited from TCustomMSDataSet)

GetBlob (inherited from TMemDataSet)

Removes WHERE clausefrom the SQL property andassigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether aparameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.

© 2019 DevartReference

701

Returns internal field types
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
GetDataType (inherited from TCustomDADataSet)

TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)© 2019 Devart

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, and702

SQL Server Data Access Components

PrepareSQL

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)parses cursor for a query.
Determines KeyFields andbuild query ofTCustomMSTable.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to© 2019 DevartReference

UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)703

the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TCustomMSTable Class
TCustomMSTable Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.5.3.1 PrepareSQL Method

Determines KeyFields and build query of TCustomMSTable.

Class
TCustomMSTable

Syntax
procedure PrepareSQL;

Remarks
Call the PrepareSQL method to determine KeyFields and build query of TCustomMSTable.
PrepareSQL is called implicitly when TCustomMSTable is being opened.

See Also
OrderFields
TableName© 2019 Devart

704

SQL Server Data Access Components

TCustomDADataSet.FilterSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6 TMSChangeNotification Class

A component for keeping information in local dataset up-to-date through receiving
notifications.
For a list of all members of this type, see TMSChangeNotification members.

Unit
MSAccess

SyntaxTMSChangeNotification = class(TComponent);

Remarks
The TMSChangeNotification component is used to register queries with the database andreceive notifications in response to DML or DDL changes on the objects associated with
queries. The notifications are published by database when the DML or DDL transaction
commits.
You should assign a TMSChangeNotification object to theTCustomMSDataSet.ChangeNotification property of the dataset you want to be notified aboutchanges. One TMSChangeNotification object can be associated with multiple datasets.
Client is notified only about changes made in the actually selected data. For example, if you
select records that match a condition from a table, notification about the changes in records
that do not match provided condition will not be received.
A notification subscription is removed after the notification event occurs. You can reopen/
refresh your dataset to get the newest data and renew the notification subscription.
The Query Notification does not support the DBPROP_UNIQUEROWS option that is required
for editable datasets. Therefore TMSChangeNotification executes an additional query
immediately after the main query has been executed, and before records have been fetched.
As the main connection is busy, OLE DB creates an additional connection to the server to
execute this query. This can slow down your application. Setting the
TMSConnectionOptions.MultipleActiveResultSets option of TMSConnection to True helps toprevent creating additional connections to server.
Requirements:
1. The Query Notifications mechanism was implemented in SQL Server 2005, therefore this© 2019 DevartReference705

component can be used starting with SQL Server 2005 and SQL Native Client.
2. Provided statement should meet restrictions described in MSDN .

See Also
TCustomMSDataSet.ChangeNotification
TCustomMSDataSet.Options
MSDN: Creating a Query for Notification
MSDN: Working with Query Notifications
MSDN: Using Query Notifications© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.1 Members

TMSChangeNotification class overview.

Properties
Name

Description
Used to enable or disableusing change notification.
Used to assign a service
manually.
Indicates the interval for a
notification to remain active.

EnabledService
TimeOut

EventsName

Description
Occurs when data in one of
the associated datasets waschanged on the server.

OnChange© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.2 Properties

Properties of the TMSChangeNotification class.
For a complete list of the TMSChangeNotification class members, see the
TMSChangeNotification Members topic.

© 2019 Devart

706

SQL Server Data Access Components

Published
Name

Description
Used to enable or disableusing change notification.
Used to assign a service
manually.
Indicates the interval for a
notification to remain active.

EnabledService
TimeOut

See Also
TMSChangeNotification ClassTMSChangeNotification Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.2.1 Enabled Property

Used to enable or disable using change notification.

Class
TMSChangeNotification

Syntaxproperty Enabled: boolean default True;

Remarks
Set the Enabled property to False to disable change notification for all datasets connected to
the TMSChangeNotification component. Setting this property to True allows datasets,connected to the TMSChangeNotification component, to use change notification.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.2.2 Service Property

Used to assign a service manually.

Class
TMSChangeNotification© 2019 DevartReference

707

Syntaxproperty Service: string;

Remarks
If this property is not assigned, TMSChangeNotification automatically creates a service andassociates it with a queue in order to receive change notifications from this queue. The nameof the automatically created service consists of the 'SDAC_NS_' prefix and the current
session identifier (SPID). The queue name consists of the service name and the '_QUEUE'
postfix. Such service and queue are created for each connection.
If several DataSet components work through the same connection associated with the
TMSChangeNotification component, only one service and one queue will be used. After all
DataSets of a connection are closed, and notifications are not necessary, the service and thequeue are dropped. Also if there are invalid services and queues at the server, they will be
dropped. A server or a queue is considered invalid if there is no connection with thecorresponding SPID. This should be done in order to prevent clogging the server with unused
services and queues, and to remove all unused notifications.
If a service name is assigned via this property, it is necessary for you to create the service
manually. The service should be created according to the rules of such object creation forQuery Notification. Manually assigned service will not be deleted by SDAC after all datasets
using it are closed. It means that the notification subscription will stay active, and when thequery is opened next time, it will be able to receive notifications.
You should remember that several applications, or several instances of the same application
using the same service name, may work incorrectly, as they will obtain notifications from thesame queue. To avoid possible problems, it is necessary to use a separate service for eachconnection (if Service is not assigned, this is done automatically).

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.13.1.6.2.3 TimeOut Property

Indicates the interval for a notification to remain active.

Class
TMSChangeNotification

Syntaxproperty TimeOut: integer default 432000;© 2019 Devart

Provide Feedback

708

SQL Server Data Access Components

Remarks
Set the TimeOut property to determine time interval in seconds, after which the notification
registration will expire.
The default value is 432000, which equals to 5 days. The minimum value is 1 second,
maximum is 2^31-1 seconds.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.3 Events

Events of the TMSChangeNotification class.
For a complete list of the TMSChangeNotification class members, see the
TMSChangeNotification Members topic.

Published
Name

Description
Occurs when data in one of
the associated datasets waschanged on the server.

OnChange

See Also
TMSChangeNotification ClassTMSChangeNotification Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.6.3.1 OnChange Event

Occurs when data in one of the associated datasets was changed on the server.

Class
TMSChangeNotification

Syntaxproperty OnChange: TMSChangeNotificationEvent;Remarks© 2019 DevartReference709

The OnChange event occurs when data in one of the associated datasets has been changedon the server. To receive change notifications the Enabled property must be set to True. The
DataSet parameter points to the dataset affected by this change. Other parameters provide
detailed information about the change.

See Also
Enabled© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7 TMSConnection Class

A component for establishing connection to the database server, providing customized login
support and performing transaction control.
For a list of all members of this type, see TMSConnection members.

Unit
MSAccess

SyntaxTMSConnection = class(TCustomMSConnection);

Remarks
TMSConnection publishes connection-related properties derived from its ancestor class
TCustomDAConnection and introduces OLE DB specific properties, which give more control
over transactions.
Note: if you would like to use SDAC in a service, console or just in a separate thread, youneed to call CoInitialize for each thread. Also call CoUnInitialize when the thread is finished.

Inheritance Hierarchy
TCustomDAConnection
TCustomMSConnection
TMSConnection

See Also
TCustomMSDataSet.Connection
TMSSQL.Connection© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

710

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.7.1 Members

TMSConnection class overview.

Properties
Name

Description
Used to specify theauthentication service used
Authenticationby the database server to
identify a user.
Contains the version of
ClientVersion (inherited from TCustomMSConnection) Microsoft OLE DB Provider
for SQL Server.
Allows to link a
ConnectDialog (inherited from TCustomDAConnection) TCustomConnectDialog
component.
Used to specify the amountof time before an attempt toConnectionTimeout
make a connection isconsidered unsuccessful.
Used to specify theConnectString (inherited from TCustomDAConnection) connection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
ConvertEOL (inherited from TCustomDAConnection) breaks in string fields andparameters.
Used to specify the
database name that is a
Database (inherited from TCustomMSConnection)
default source of data for
SQL queries once a
connection is established.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLevel (inherited from TCustomMSConnection) transactions interfere withsubsequent transactions of
the current connection.
Specifies whether a login
LoginPrompt (inherited from TCustomDAConnection) dialog appears immediately
before opening a new© 2019 DevartReference

Options
Password (inherited from TCustomDAConnection)
Pooling (inherited from TCustomDAConnection)
PoolingOptions (inherited fromTCustomDAConnection)

711

connection.
Used to specify the
behaviour of a
TMSConnection object.
Serves to supply apassword for login.
Enables or disables using
connection pool.
Specifies the behaviour ofconnection pool.

Used to specify the port
number for the connection.
Serves to supply the server
Server (inherited from TCustomDAConnection)
name for login.
ServerVersion (inherited from TCustomMSConnection) Contains the exact numberof the SQL Server version.
Used to supply a user name
Username (inherited from TCustomDAConnection)
for login.
Port

Methods
Name

Description
ApplyUpdates (inherited from TCustomDAConnection) Overloaded. Applies
changes in datasets.
Shares database
AssignConnect (inherited fromconnection between the
TCustomMSConnection)
TCustomMSConnection
components.
Assignes a new password
ChangePassword
instead of an expired one..
Commit (inherited from TCustomDAConnection)
Commits current transaction.
Connect (inherited from TCustomDAConnection)

CreateSQL (inherited from TCustomMSConnection)
Disconnect (inherited from TCustomDAConnection)
ExecProc (inherited from TCustomDAConnection)© 2019 Devart

Establishes a connection to
the server.
Returns a new instance of
the TMSSQL class andassociates it with thisconnection object.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.

712

SQL Server Data Access Components

ExecProcEx (inherited from TCustomDAConnection)
ExecSQL (inherited from TCustomDAConnection)

ExecSQLEx (inherited from TCustomDAConnection)
GetDatabaseNames (inherited fromTCustomDAConnection)
GetKeyFieldNames (inherited fromTCustomDAConnection)
GetStoredProcNames (inherited fromTCustomDAConnection)
GetTableNames (inherited fromTCustomDAConnection)

Allows to execute a stored
procedure or function.
Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.
Provides a list of available
key field names.
Returns a list of stored
procedures from the server.
Provides a list of available
tables names.

Sends a specified message
through theTCustomDAConnection)
TCustomDASQLMonitor
component.
OpenDatasets (inherited from TCustomMSConnection) Opens several datasets as
one batch.
Used to check state ofPing (inherited from TCustomDAConnection)connection to the server.
Marks the connection that
RemoveFromPool (inherited fromshould not be returned to theTCustomDAConnection)
pool after disconnect.
Discards all current data
Rollback (inherited from TCustomDAConnection)changes and ends
transaction.
StartTransaction (inherited fromBegins a new user
MonitorMessage (inherited fromTCustomDAConnection)transaction.

EventsName
OnConnectionLost (inherited fromTCustomDAConnection)

Description
This event occurs whenconnection was lost.

© 2019 DevartReference

OnError (inherited from TCustomDAConnection)
OnInfoMessage© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

713

This event occurs when anerror has arisen in theconnection.
Occurs if a SQL Server info
message was generated.
Provide Feedback

5.13.1.7.2 Properties

Properties of the TMSConnection class.
For a complete list of the TMSConnection class members, see the TMSConnection
Members topic.

PublicName

Description
Contains the version of
ClientVersion (inherited from TCustomMSConnection) Microsoft OLE DB Provider
for SQL Server.
Allows to link a
ConnectDialog (inherited from TCustomDAConnection) TCustomConnectDialog
component.
Used to specify theConnectString (inherited from TCustomDAConnection) connection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
ConvertEOL (inherited from TCustomDAConnection) breaks in string fields andparameters.
Used to specify the
database name that is a
Database (inherited from TCustomMSConnection)
default source of data for
SQL queries once a
connection is established.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLevel (inherited from TCustomMSConnection) transactions interfere withsubsequent transactions of
the current connection.

© 2019 Devart

714

SQL Server Data Access Components

LoginPrompt (inherited from TCustomDAConnection)

Password (inherited from TCustomDAConnection)
Pooling (inherited from TCustomDAConnection)
PoolingOptions (inherited fromSpecifies whether a login
dialog appears immediately
before opening a newconnection.
Serves to supply apassword for login.
Enables or disables using
connection pool.
Specifies the behaviour ofconnection pool.

TCustomDAConnection)

Serves to supply the server
name for login.
ServerVersion (inherited from TCustomMSConnection) Contains the exact numberof the SQL Server version.
Used to supply a user name
Username (inherited from TCustomDAConnection)
for login.
Server (inherited from TCustomDAConnection)

Published
Name

Description
Used to specify theauthentication service usedby the database server to
identify a user.
Used to specify the amountof time before an attempt tomake a connection isconsidered unsuccessful.
Used to specify the
behaviour of a
TMSConnection object.
Used to specify the port
number for the connection.

Authentication

ConnectionTimeout

OptionsPort

See Also
TMSConnection ClassTMSConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference715

5.13.1.7.2.1 Authentication Property

Used to specify the authentication service used by the database server to identify a user.

Class
TMSConnection

Syntaxproperty Authentication: TMSAuthentication default
DefValAuthentication;

Remarks
Use the Authentication property to specify the authentication service used by the databaseserver to identify a user.
If you need to use this property at run-time, you must use the OLEDBAccess unit.

See Also
TCustomDAConnection.Username
TCustomDAConnection.Password© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7.2.2 ConnectionTimeout Property

Used to specify the amount of time before an attempt to make a connection is considered
unsuccessful.

Class
TMSConnection

Syntaxproperty ConnectionTimeout: integer default
DefValConnectionTimeout;

Remarks
Use the ConnectionTimeout property to specify the amount of time in seconds before an
attempt to make a connection is considered unsuccessful.
The default value is 15 seconds.

© 2019 Devart

716

SQL Server Data Access Components

See Also
TCustomMSDataSet.CommandTimeout
TMSSQL.CommandTimeout© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7.2.3 Options Property

Used to specify the behaviour of a TMSConnection object.

Class
TMSConnection

Syntaxproperty Options: TMSConnectionOptions;Remarks
Set the properties of Options to specify the behaviour of a TMSConnection object.
Descriptions of all options are in the table below.

Option Name
ApplicationIntent
ApplicationName

AutoTranslate
DefaultLockTimeout
Encrypt
FailoverPartner

ForceCreateDatabase
InitialFileName

Description
Used to specify the application workload
type when connecting to a server.
The name of a client application. The
default value is the name of the executable
file of your application.
Used to translate character strings sent
between the client and server by converting
through Unicode.
Specifies how much time in milliseconds atransaction will wait for a lock.
Specifies if data should be encrypted
before sending it over the network.
Specifies the SQL Server name to which
SQL Native Client will reconnect when afailover of the principal SQL Server occurs.
Used to force TMSConnection to create a
new database before opening aconnection, if the database is not exists.
Specifies the name of the main database© 2019 DevartReference

IPVersion
Language
MultipleActiveResultSets
MultipleConnections
NativeClientVersion
NetworkLibrary
PacketSize
PersistSecurityInfo

ProviderTrustServerCertificate
WorkstationID© 1997-2019
Devart. All Rights
Reserved.

Request Support

717

file.
Use the IPVersion property to specify
Internet Protocol Version. The default value
is ivIPv4.
Specifies the SQL Server language name.
Enables support for the Multiple Active
Result Sets (MARS) technology.
Enables and disables to create additional
connections to support concurrent
sessions, commands and rowset objects.
Specifies which version of SQL Native
Client will be used.
Specifies the name of the Net-Library(DLL) used to communicate with an
instance of SQL Server.
Network packet size in bytes.
Used to allow the data source object topersist sensitive authentication informationsuch as a password along with otherauthentication information.
Used to specify a provider from the list of
supported providers.
Used to enable traffic encryption without
validation.
A string identifying the workstation.
DAC Forum

Provide Feedback

5.13.1.7.2.4 Port Property

Used to specify the port number for the connection.

Class
TMSConnection

Syntaxproperty Port: integer default DefaultSDACPort;

Remarks
Use the Port property to specify the port number for the connection. The default value is 1433.
Note 1: If the Server property contains a port (for example, Server=localhost,1434 ), the Port
© 2019 Devart

718

SQL Server Data Access Components

property is ignored.
Note 2: If the Port property is set to the default value 1433, and the Server property does notcontain a port or is blank, the Port property is ignored. In this case, the used provider (OLEDBor SQL Native Client) performs searching on the specified server for the correct port that islistened by SQL Server and uses it to connect to the server.

See Also
TCustomDAConnection.Server© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7.3 Methods

Methods of the TMSConnection class.
For a complete list of the TMSConnection class members, see the TMSConnection
Members topic.

PublicName

Description
ApplyUpdates (inherited from TCustomDAConnection) Overloaded. Applies
changes in datasets.
Shares database
AssignConnect (inherited fromconnection between the
TCustomMSConnection)
TCustomMSConnection
components.
Assignes a new password
ChangePassword
instead of an expired one..
Commit (inherited from TCustomDAConnection)
Commits current transaction.
Connect (inherited from TCustomDAConnection)

CreateSQL (inherited from TCustomMSConnection)
Disconnect (inherited from TCustomDAConnection)
ExecProc (inherited from TCustomDAConnection)

ExecProcEx (inherited from TCustomDAConnection)

Establishes a connection to
the server.
Returns a new instance of
the TMSSQL class andassociates it with thisconnection object.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
© 2019 DevartReference

ExecSQL (inherited from TCustomDAConnection)

ExecSQLEx (inherited from TCustomDAConnection)
GetDatabaseNames (inherited from719

Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.

TCustomDAConnection)
GetKeyFieldNames (inherited from

Provides a list of available
key field names.

TCustomDAConnection)
GetStoredProcNames (inherited fromReturns a list of stored
procedures from the server.

TCustomDAConnection)
GetTableNames (inherited from

Provides a list of available
tables names.

TCustomDAConnection)

Sends a specified message
through theTCustomDAConnection)
TCustomDASQLMonitor
component.
OpenDatasets (inherited from TCustomMSConnection) Opens several datasets as
one batch.
Used to check state ofPing (inherited from TCustomDAConnection)connection to the server.
Marks the connection that
RemoveFromPool (inherited fromshould not be returned to theTCustomDAConnection)
pool after disconnect.
Discards all current data
Rollback (inherited from TCustomDAConnection)changes and ends
transaction.
StartTransaction (inherited fromBegins a new user
MonitorMessage (inherited fromTCustomDAConnection)transaction.

See Also
TMSConnection ClassTMSConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

720

SQL Server Data Access Components

5.13.1.7.3.1 ChangePassw ord Method

Assignes a new password instead of an expired one..

Class
TMSConnection

Syntax
procedure ChangePassword(const NewPassword: string);
Parameters
NewPassword
Holds the new password assigned.

Remarks
Use the ChangePassword method to change an expired user's password. In SQL Server
versions prior to SQL Server 2005 only a database administrator has permissions to change
an expired user's password. Starting from SQL Server 2005 you can change it using theChangePassword method and SQL Native Client.
Note: Only an expired user's password can be changed using this method.

See Also
MSDN: Changing Passwords Programmatically© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7.4 Events

Events of the TMSConnection class.
For a complete list of the TMSConnection class members, see the TMSConnection
Members topic.

PublicName
OnConnectionLost (inherited fromTCustomDAConnection)
OnError (inherited from TCustomDAConnection)

Description
This event occurs whenconnection was lost.
This event occurs when anerror has arisen in theconnection.
© 2019 DevartReference

721

Published
Name

Description
Occurs if a SQL Server info
message was generated.

OnInfoMessage

See Also
TMSConnection ClassTMSConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.7.4.1 OnInfoMessage Event

Occurs if a SQL Server info message was generated.

Class
TMSConnection

Syntaxproperty OnInfoMessage: TMSConnectionInfoMessageEvent;Remarks
The OnInfoMessage event occurs in case of generation of a SQL Server info message. The
event occurs only if the command is executed through a dataset descendant (TMSQuery,
TMSStoredProc). To make this event occur for TMSScript, TMSScript.DataSet should be set.
It does not work for TMSSQL. The following is the list of Transact-SQL commands thatgenerate info messages:
PRINT
RAISERROR with a severity of 10 or lower
DBCC
SET SHOWPLANSET STATISTICS.

See Also
EMSError© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

722

SQL Server Data Access Components

Reserved.
5.13.1.8 TMSConnectionOptions ClassThis class allows setting up the behaviour of the TMSConnection class.
For a list of all members of this type, see TMSConnectionOptions members.

Unit
MSAccess

SyntaxTMSConnectionOptions = class(TCustomMSConnectionOptions);

Inheritance Hierarchy
TDAConnectionOptions
TCustomMSConnectionOptions
TMSConnectionOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.1 Members

TMSConnectionOptions class overview.

Properties
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)ApplicationIntent

ApplicationName

AutoTranslate

Description
Specifies whether to allow or
not implicit connection
opening.
Used to specify theapplication workload typewhen connecting to a server.
The name of a client
application. The default
value is the name of theexecutable file of yourapplication.
Used to translate character
strings sent between theclient and server by
converting through Unicode.
© 2019 DevartReference

723

Specifies how much time inmilliseconds a transaction
will wait for a lock.
Used to determine thedefault type of local sortingfor string fields. It is used
DefaultSortType (inherited fromwhen a sort type is not
TDAConnectionOptions)specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa
mes property of a dataset.
Used to open a connection
only when needed for
DisconnectedMode (inherited fromperforming a server call and
TDAConnectionOptions)closes after performing theoperation.
Specifies if data should be
Encrypt
encrypted before sending itover the network.
Specifies the SQL Server
name to which SQL Native
FailoverPartner
Client will reconnect when afailover of the principal SQL
Server occurs.
Used to force
TMSConnection to create a
ForceCreateDatabasenew database before
opening a connection, if thedatabase is not exists.
Specifies the name of theInitialFileName
main database file.
Use the IPVersion property
to specify Internet Protocol
IPVersion
Version. The default value isivIPv4.
Used to prevent an
KeepDesignConnected (inherited fromapplication from establishing
TDAConnectionOptions)a connection at the time ofstartup.
Specifies the SQL Server
Language
language name.
If True, theLocalFailover (inherited from TDAConnectionOptions) TCustomDAConnection.On
ConnectionLost event
occurs and a failover
DefaultLockTimeout© 2019 Devart

724

SQL Server Data Access Components

MultipleActiveResultSets

MultipleConnections

NativeClientVersion

NetworkLibrary

NumericType (inherited fromTCustomMSConnectionOptions)

PacketSize

PersistSecurityInfo

ProviderQuotedIdentifier (inherited fromTCustomMSConnectionOptions)
TrustServerCertificate
UseWideMemos (inherited fromTCustomMSConnectionOptions)operation can be performed
after connection breaks.
Enables support for theMultiple Active Result Sets
(MARS) technology.
Enables and disables tocreate additional
connections to support
concurrent sessions,commands and rowset
objects.
Specifies which version of
SQL Native Client will be
used.
Specifies the name of the
Net-Library (DLL) used tocommunicate with an
instance of SQL Server.
Specifies the format ofstoring and representing the
NUMERIC (DECIMAL) fields
for all TCustomMSDataSets
associated with the given
connection.
Network packet size inbytes.
Used to allow the data
source object to persist
sensitive authentication
information such as a
password along with otherauthentication information.
Used to specify a provider
from the list of supported
providers.
Causes Microsoft SQL
Server to follow the SQL-92
rules regarding quotation
mark delimiting identifiers
and literal strings.
Used to enable traffic
encryption without validation.
Used to manage field typecreation for the NTEXT data
type.
© 2019 DevartReference

A string identifying theworkstation.

WorkstationID© 1997-2019
Devart. All Rights
Reserved.

725

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2 Properties

Properties of the TMSConnectionOptions class.
For a complete list of the TMSConnectionOptions class members, see the
TMSConnectionOptions Members topic.

PublicName

Description
Used to determine thedefault type of local sortingfor string fields. It is used
DefaultSortType (inherited fromwhen a sort type is not
TDAConnectionOptions)specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa
mes property of a dataset.
Used to open a connection
only when needed for
DisconnectedMode (inherited fromperforming a server call and
TDAConnectionOptions)closes after performing theoperation.
Used to prevent an
KeepDesignConnected (inherited fromapplication from establishing
TDAConnectionOptions)a connection at the time ofstartup.
If True, theTCustomDAConnection.On
LocalFailover (inherited from TDAConnectionOptions) ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.
Specifies the format ofstoring and representing the
NumericType (inherited fromNUMERIC (DECIMAL) fields
TCustomMSConnectionOptions)for all TCustomMSDataSets
associated with the given
connection.
© 2019 Devart

726

SQL Server Data Access Components

QuotedIdentifier (inherited fromTCustomMSConnectionOptions)
UseWideMemos (inherited fromTCustomMSConnectionOptions)

Causes Microsoft SQL
Server to follow the SQL-92
rules regarding quotation
mark delimiting identifiers
and literal strings.
Used to manage field typecreation for the NTEXT data
type.

Published
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)ApplicationIntent

ApplicationName

AutoTranslate

DefaultLockTimeout

Encrypt

FailoverPartner

ForceCreateDatabase

InitialFileName

Description
Specifies whether to allow or
not implicit connection
opening.
Used to specify theapplication workload typewhen connecting to a server.
The name of a client
application. The default
value is the name of theexecutable file of yourapplication.
Used to translate character
strings sent between theclient and server by
converting through Unicode.
Specifies how much time inmilliseconds a transaction
will wait for a lock.
Specifies if data should beencrypted before sending itover the network.
Specifies the SQL Server
name to which SQL Native
Client will reconnect when afailover of the principal SQL
Server occurs.
Used to force
TMSConnection to create a
new database before
opening a connection, if thedatabase is not exists.
Specifies the name of the© 2019 DevartReference

727

main database file.
Use the IPVersion property
to specify Internet Protocol
Version. The default value isivIPv4.
Specifies the SQL Server
language name.
Enables support for theMultiple Active Result Sets
(MARS) technology.
Enables and disables tocreate additional
connections to support
concurrent sessions,commands and rowset
objects.
Specifies which version of
SQL Native Client will be
used.
Specifies the name of the
Net-Library (DLL) used tocommunicate with an
instance of SQL Server.
Network packet size inbytes.
Used to allow the data
source object to persist
sensitive authentication
information such as a
password along with otherauthentication information.
Used to specify a provider
from the list of supported
providers.
Used to enable traffic
encryption without validation.
A string identifying theworkstation.

IPVersion

Language
MultipleActiveResultSets

MultipleConnections

NativeClientVersion

NetworkLibrary

PacketSize

PersistSecurityInfo

ProviderTrustServerCertificate
WorkstationID

See Also
TMSConnectionOptions ClassTMSConnectionOptions Class Members© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

728

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.8.2.1 ApplicationIntent Property

Used to specify the application workload type when connecting to a server.

Class
TMSConnectionOptions

Syntaxproperty ApplicationIntent: TApplicationIntent default
DefValApplicationIntent;

Remarks
Use the ApplicationIntent property to specify the application workload type. The default value
is aiReadWrite.

See Also
SQL Server Native Client Support for High Availability, Disaster Recovery
Using Connection String Keywords with SQL Server Native Client© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.2 ApplicationName Property

The name of a client application. The default value is the name of the executable file of yourapplication.

Class
TMSConnectionOptions

Syntaxproperty ApplicationName: string;

Remarks
Use the ApplicationName property to specify the name of a client application. The default
value is the name of the executable file of your application.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference729

Devart. All Rights
Reserved.
5.13.1.8.2.3 AutoTranslate Property

Used to translate character strings sent between the client and server by converting throughUnicode.

Class
TMSConnectionOptions

Syntaxproperty AutoTranslate: boolean default DefValAutoTranslate;

Remarks
When set to True, character strings sent between the client and server are translated byconverting through Unicode to minimize problems in matching extended characters between
the code pages on the client and server.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.4 DefaultLockTimeout Property

Specifies how much time in milliseconds a transaction will wait for a lock.

Class
TMSConnectionOptions

Syntaxproperty DefaultLockTimeout: integer;

Remarks
Use the DefaultLockTimeout property to specify how much time in milliseconds a transaction
will wait for a lock. The default value is 2000 ms.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

730

SQL Server Data Access Components

5.13.1.8.2.5 Encrypt Property

Specifies if data should be encrypted before sending it over the network.

Class
TMSConnectionOptions

Syntaxproperty Encrypt: boolean;

Remarks
Use the Encrypt property to specify if data should be encrypted before sending it over the
network. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.6 FailoverPartner Property

Specifies the SQL Server name to which SQL Native Client will reconnect when a failover ofthe principal SQL Server occurs.

Class
TMSConnectionOptions

Syntaxproperty FailoverPartner: string;

Remarks
Use the FailoverPartner property to specify the SQL Server name to which SQL Native Client
will reconnect when a failover of the principal SQL Server occurs. This option is supported
since SQL Server 2005 using SQL Native Client as OLE DB provider.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.7 ForceCreateDatabase Property

Used to force TMSConnection to create a new database before opening a connection, if thedatabase is not exists.

© 2019 DevartReference

731

Class
TMSConnectionOptions

Syntaxproperty ForceCreateDatabase: boolean;

Remarks
By default, when connecting to a database, SQL Server does not check whether there exists
the specified file. If the TCustomMSConnection.Database property points to a non-existent
database in correct system path, a new empty database will be created and opened, and no
warning message will be displayed. In the case if an incorrect database name was entered by
mistake, this behavior can lead to misunderstandings and errors in the operation of thesoftware.
If the TMSConnectionOptions.ForceDatabaseCreate property is set to False, before
establishing a connection to the database, P:Devart.Sdac.TCustomMSConnection will check
whether the specified file exists. If the file does not exist, an appropriate exception will beraised.
If the TMSConnectionOptions.ForceDatabaseCreate property is set to True, no checking will
be performed and a new database will be created.
The default value of the TMSConnectionOptions.ForceDatabaseCreate property is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.8 InitialFileName Property

Specifies the name of the main database file.

Class
TMSConnectionOptions

Syntaxproperty InitialFileName: string;

Remarks
Use the InitialFileName property to specify the name of the main database file. This database
will be the default database for the connection. SQL Server attaches the database to theserver if it has not been attached to the server yet. So, this property can be used to connect to© 2019 Devart

732

SQL Server Data Access Components

the database that has not been attached to the server yet.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.9 IPVersion Property

Use the IPVersion property to specify Internet Protocol Version. The default value is ivIPv4.

Class
TMSConnectionOptions

Syntaxproperty IPVersion: TIPVersion;

Remarks
Use the IPVersion property to specify Internet Protocol Version.
Supported values:ivIPBoth - specifies that either Internet Protocol Version 6 (IPv6) or Version 4 (IPv4) will be
used;
ivIPv4 (default) - specifies that Internet Protocol Version 4 (IPv4) will be used;ivIPv6 - specifies that Internet Protocol Version 6 (IPv6) will be used.
Note : When the TIPVersion property is set to ivIPBoth, a connection attempt will be made via
IPv6 if it is enabled on the operating system. If the connection attempt fails, a new connection
attempt will be made via IPv4.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.10 Language Property

Specifies the SQL Server language name.

Class
TMSConnectionOptions

Syntaxproperty Language: string;© 2019 DevartReference

733

Remarks
Use the Language property to specify the SQL Server language name. Identifies the language
used for system message selection and formatting. The language must be installed on thecomputer running an instance of SQL Server otherwise the connection will fail.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.11 MultipleActiveResultSets Property

Enables support for the Multiple Active Result Sets (MARS) technology.

Class
TMSConnectionOptions

Syntaxproperty MultipleActiveResultSets: boolean default
DefValMultipleActiveResultSets;

Remarks
Use the MultipleActiveResultSets property to enable support for the Multiple Active Result
Sets (MARS) technology. It allows applications to have more than one pending request perconnection, and, in particular, to have more than one active default result set per connection.
Current session is not blocked when using FetchAll = False, and it is not necessary for OLE
DB to create additional sessions for any query executing. MARS was supported in SQL
Server versions since SQL Server 2005 with using SQL Native Client as OLE DB provider.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.12 MultipleConnections Property

Enables and disables to create additional connections to support concurrent sessions,commands and rowset objects.

Class
TMSConnectionOptions

Syntax© 2019 Devart

734

SQL Server Data Access Components

property MultipleConnections: boolean default
DefValMultipleConnections;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.13 NativeClientVersion Property

Specifies which version of SQL Native Client will be used.

Class
TMSConnectionOptions

Syntaxproperty NativeClientVersion: TNativeClientVersion;

Remarks
Use the NativeClientVersion property to specify which version of SQL Native Client will be
used. The default value is ncAuto. NativeClientVersion is applied when the Provider property
is set to prNativeClient or prAuto.

See Also
Provider© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.14 Netw orkLibrary Property

Specifies the name of the Net-Library (DLL) used to communicate with an instance of SQL
Server.

Class
TMSConnectionOptions

Syntaxproperty NetworkLibrary: string;

Remarks
The name of the Net-Library (DLL) used to communicate with an instance of SQL Server.

© 2019 DevartReference735

The name should not include the path or the .dll file name extension. The default name isprovided by SQL Server Client Network Utility.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.15 PacketSize Property

Network packet size in bytes.

Class
TMSConnectionOptions

Syntaxproperty PacketSize: integer default DefaultPacketSize;

Remarks
Use the PacketSize property to specify the network packet size in bytes. The packet size
property value must be between 512 and 32,767. The default network packet size is 4,096.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.16 PersistSecurityInfo Property

Used to allow the data source object to persist sensitive authentication information such as a
password along with other authentication information.

Class
TMSConnectionOptions

Syntaxproperty PersistSecurityInfo: boolean default
DefValPersistSecurityInfo;

Remarks
If True, the data source object is allowed to persist sensitive authentication information suchas a password along with other authentication information.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

736

SQL Server Data Access Components

Reserved.
5.13.1.8.2.17 Provider Property

Used to specify a provider from the list of supported providers.

Class
TMSConnectionOptions

Syntaxproperty Provider: TMSProvider;

Remarks
Use the Provider property to specify a provider from the list of supported providers. The
default value of this property is prAuto. In this case a provider of the most recent version isused. Some features in SQL Server require the SQL Native Client (prNativeClient) provider tobe used. If chosen provider is not installed, an exception is raised. The prCompact value
should be set for working with SQL Server Compact Edition.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.8.2.18 TrustServerCertificate Property

Used to enable traffic encryption without validation.

Class
TMSConnectionOptions

Syntaxproperty TrustServerCertificate: boolean default
DefValTrustServerCertificate;

Remarks
Use the TrustServerCertificate property to enable traffic encryption without validation. The
default value is False. This option is supported since SQL Server 2005 with using SQL Native
Client as OLE DB provider.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

737

5.13.1.8.2.19 WorkstationID Property

A string identifying the workstation.

Class
TMSConnectionOptions

Syntaxproperty WorkstationID: string;

Remarks
A string identifying the workstation. The default value is the name of your machine.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9 TMSDataSetOptions ClassThis class allows setting up the behaviour of the TMSDataSet class.
For a list of all members of this type, see TMSDataSetOptions members.

Unit
MSAccess

SyntaxTMSDataSetOptions = class(TDADataSetOptions);

Inheritance Hierarchy
TDADataSetOptions
TMSDataSetOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.1 Members

TMSDataSetOptions class overview.

Properties
Name© 2019 Devart

Description

738

SQL Server Data Access Components

AllFieldsEditable

Not supported.
Used to execute automatic
AutoPrepare
TCustomDADataSet.Prepar
e on a query execution.
Used to enable automaticrefresh of a dataset every
AutoRefresh
AutoRefreshInterval
seconds.
Used to define in what timeinterval in seconds theRefresh or
AutoRefreshInterval
TCustomMSDataSet.Refres
hQuick method of DataSet
is called.
Used to enable caching of
CacheCalcFields (inherited from TDADataSetOptions) the TField.Calculated and
TField.Lookup fields.
Used to determine whether
dataset checks for rows
modifications made by
CheckRowVersion
another user on automatic
generation of SQL
statement for update ordelete data.
Used to store values of theCompressBlobMode (inherited from
BLOB fields in compressed
TDADataSetOptions)
form.
Used to specify the way data
updates reflect on database
CursorUpdate
when modifying dataset byusing server cursors
ctKeySet and ctDynamic.
Used to enable
TCustomMSDataSet to fill
DefaultValues
the DefaultExpression
property of TField objects by
an appropriate value.
Used to specify whether toquery TMSParam properties
from the server when
DescribeParams
executing theTCustomDADataSet.Prepar
e method.
DetailDelay (inherited from TDADataSetOptions)
Used to get or set a delay in© 2019 DevartReference

739

milliseconds before
refreshing detail dataset
while navigating masterdataset.
Used to forbid multiple
DisableMultipleResults
results usage by acommand.
Used to refresh a record
DMLRefresh
when insertion or update is
performed.
Used to specify whether toEnableBCD
treat numeric fields as
floating-point or BCD.
Used forTCustomDADataSet to fill
the Origin property of theFieldsOrigin (inherited from TDADataSetOptions)
TField objects byappropriate value when
opening a dataset.
Used to control how adataset treats data of the
FlatBuffers (inherited from TDADataSetOptions)
ftString and ftVarBytes
fields.
Used to specify the fields toinclude in the automaticallygenerated SQL statement
FullRefresh
when calling theTCustomDADataSet.Refres
hRecord method.
Used to hide system fields
for the prSQL,
HideSystemUniqueFields
prNativeClient and
prMSOLEDB providers. The
default value is True.
Used to include all set
InsertAllSetFields (inherited from TDADataSetOptions) dataset fields in thegenerated INSERT
statement
Determines which system
function to use to obtain an
LastIdentityValueFunction
identifier when adding arecord. The default value is
vfScopeIdentity.
LocalMasterDetail (inherited from TDADataSetOptions) Used forTCustomDADataSet to use© 2019 Devart

740

SQL Server Data Access Components

LongStrings

MasterFieldsNullable (inherited from
TDADataSetOptions)

NonBlocking

NumberRange

PrepareUpdateSQLQueryIdentity

QueryRecCount

QuoteNames

ReflectChangeNotify

local filtering to establish
master/detail relationship for
detail dataset and does notrefer to the server.
Represents string fields withthe length that is greater than
255 as TStringField.
Allows to use NULL values
in the fields by which therelation is built, whengenerating the query for the
Detail tables (when thisoption is enabled, theperformance can get worse).
Used to fetch rows in a
separate thread.
Used to set the MaxValueand MinValue properties of
TIntegerField and
TFloatField to appropriate
values.
Used to automatically
prepare update queries
before execution.
Used to specify whether torequest the Identity fieldvalue on execution of theInsert or Append method.
Used to perform additional
query to get record count forthis SELECT, so the
RecordCount property
reflects the actual number ofrecords.
Used forTCustomMSDataSet toquote all field names in
autogenerated SQL
statements.
Indicates whether DataSet
will be automaticallyrefreshed when theunderlying data on the serveris changed.

© 2019 DevartReference

741

Used for dataset to locallyremove record on refresh if it
RemoveOnRefresh
does not match filter
condition (WHERE clause
for refresh SQL) anymore.
Used forTCustomMSDataSet to set
RequiredFields
the Required property of
TField objects for the NOTNULL fields.
Used to return the new
ReturnParams
values of fields to dataset
after insert or update.
Force replace of empty
SetEmptyStrToNull
strings with NULL values indata. Default value is False.
Used for a dataset to set the
ReadOnly property to True
SetFieldsReadOnly (inherited fromfor all fields that do not
TDADataSetOptions)belong to UpdatingTable or
can not be updated.
Used forTCustomDADataSet toraise an exception when the
StrictUpdate
number of updated ordeleted records is not equal
1.
Used to specify whether todiscard all trailing spaces in
TrimFixedChar
the fixed-length string fields
of a dataset.
Used to specify whether todiscard all trailing spaces in
TrimVarChar
the variable-length string
fields of a dataset.
Used to specify whether to
UniqueRecords
query additional keyfields
from the server.
Used to include all dataset
fields in the generated
UpdateAllFields (inherited from TDADataSetOptions)
UPDATE and INSERT
statements.
Used to get or set a value
UpdateBatchSize (inherited from TDADataSetOptions) that enables or disables
batch processing support,© 2019 Devart

742

SQL Server Data Access Components

and specifies the number ofcommands that can be
executed in a batch.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2 Properties

Properties of the TMSDataSetOptions class.
For a complete list of the TMSDataSetOptions class members, see the
TMSDataSetOptions Members topic.

PublicName
AllFieldsEditable

Description
Not supported.
Used to enable caching of
CacheCalcFields (inherited from TDADataSetOptions) the TField.Calculated and
TField.Lookup fields.
Used to store values of theCompressBlobMode (inherited from
BLOB fields in compressed
TDADataSetOptions)
form.
Used to get or set a delay inmilliseconds before
DetailDelay (inherited from TDADataSetOptions)refreshing detail dataset
while navigating masterdataset.
Used forTCustomDADataSet to fill
the Origin property of theFieldsOrigin (inherited from TDADataSetOptions)
TField objects byappropriate value when
opening a dataset.
Used to control how adataset treats data of the
FlatBuffers (inherited from TDADataSetOptions)
ftString and ftVarBytes
fields.
Used to include all set
InsertAllSetFields (inherited from TDADataSetOptions) dataset fields in thegenerated INSERT
statement
LocalMasterDetail (inherited from TDADataSetOptions) Used forTCustomDADataSet to use© 2019 DevartReference743

local filtering to establish
master/detail relationship for
detail dataset and does notrefer to the server.
Allows to use NULL values
in the fields by which therelation is built, when
MasterFieldsNullable (inherited fromgenerating the query for the
TDADataSetOptions)
Detail tables (when thisoption is enabled, theperformance can get worse).
Used for a dataset to set the
ReadOnly property to True
SetFieldsReadOnly (inherited fromfor all fields that do not
TDADataSetOptions)belong to UpdatingTable or
can not be updated.
Used to include all dataset
fields in the generated
UpdateAllFields (inherited from TDADataSetOptions)
UPDATE and INSERT
statements.
Used to get or set a valuethat enables or disables
UpdateBatchSize (inherited from TDADataSetOptions) batch processing support,
and specifies the number ofcommands that can be
executed in a batch.

Published
Name
AutoPrepare

AutoRefresh

AutoRefreshInterval

CheckRowVersion© 2019 Devart

Description
Used to execute automatic
TCustomDADataSet.Prepar
e on a query execution.
Used to enable automaticrefresh of a dataset every
AutoRefreshInterval
seconds.
Used to define in what timeinterval in seconds theRefresh or
TCustomMSDataSet.Refres
hQuick method of DataSet
is called.
Used to determine whether

744

SQL Server Data Access Components

CursorUpdate

DefaultValues

DescribeParams

DisableMultipleResults

DMLRefresh

EnableBCD

FullRefresh

HideSystemUniqueFields

LastIdentityValueFunction

dataset checks for rows
modifications made byanother user on automatic
generation of SQL
statement for update ordelete data.
Used to specify the way data
updates reflect on databasewhen modifying dataset byusing server cursors
ctKeySet and ctDynamic.
Used to enable
TCustomMSDataSet to fill
the DefaultExpression
property of TField objects by
an appropriate value.
Used to specify whether toquery TMSParam properties
from the server when
executing theTCustomDADataSet.Prepar
e method.
Used to forbid multiple
results usage by acommand.
Used to refresh a record
when insertion or update is
performed.
Used to specify whether totreat numeric fields as
floating-point or BCD.
Used to specify the fields toinclude in the automaticallygenerated SQL statement
when calling theTCustomDADataSet.Refres
hRecord method.
Used to hide system fields
for the prSQL,
prNativeClient and
prMSOLEDB providers. The
default value is True.
Determines which system
function to use to obtain an
identifier when adding a© 2019 DevartReference

LongStrings
NonBlocking

NumberRange

PrepareUpdateSQLQueryIdentity

QueryRecCount

QuoteNames

ReflectChangeNotify

RemoveOnRefresh

RequiredFields© 2019 Devart

745

record. The default value is
vfScopeIdentity.
Represents string fields withthe length that is greater than
255 as TStringField.
Used to fetch rows in a
separate thread.
Used to set the MaxValueand MinValue properties of
TIntegerField and
TFloatField to appropriate
values.
Used to automatically
prepare update queries
before execution.
Used to specify whether torequest the Identity fieldvalue on execution of theInsert or Append method.
Used to perform additional
query to get record count forthis SELECT, so the
RecordCount property
reflects the actual number ofrecords.
Used forTCustomMSDataSet toquote all field names in
autogenerated SQL
statements.
Indicates whether DataSet
will be automaticallyrefreshed when theunderlying data on the serveris changed.
Used for dataset to locallyremove record on refresh if it
does not match filter
condition (WHERE clause
for refresh SQL) anymore.
Used forTCustomMSDataSet to set
the Required property of
TField objects for the NOTNULL fields.

746

SQL Server Data Access Components

Used to return the newvalues of fields to dataset
after insert or update.
Force replace of empty
strings with NULL values indata. Default value is False.
Used forTCustomDADataSet toraise an exception when thenumber of updated ordeleted records is not equal
1.
Used to specify whether todiscard all trailing spaces in
the fixed-length string fields
of a dataset.
Used to specify whether todiscard all trailing spaces inthe variable-length string
fields of a dataset.
Used to specify whether toquery additional keyfields
from the server.

ReturnParams

SetEmptyStrToNull

StrictUpdate

TrimFixedChar

TrimVarChar

UniqueRecords

See Also
TMSDataSetOptions ClassTMSDataSetOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.1 AllFieldsEditable Property

Not supported.

Class
TMSDataSetOptions

Syntaxproperty AllFieldsEditable: boolean;

Remarks© 2019 DevartReference

747

Refer to TCustomDADataSet.Options.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.2 AutoPrepare Property

Used to execute automatic TCustomDADataSet.Prepare on a query execution.

Class
TMSDataSetOptions

Syntaxproperty AutoPrepare: boolean;

Remarks
Use the AutoPrepare property to execute automatic TCustomDADataSet.Prepare on a query
execution. Makes sense for the cases when a query will be executed several times, forexample, in Master/Detail relationships.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.3 AutoRefresh Property

Used to enable automatic refresh of a dataset every AutoRefreshInterval seconds.

Class
TMSDataSetOptions

Syntaxproperty AutoRefresh: boolean default False;

Remarks
If True, dataset will be automatically refreshed every AutoRefreshInterval seconds. If dataset
has at least one key field and a TIMESTAMP field, the TCustomMSDataSet.RefreshQuick
method will be executed, otherwise the Refresh method will be executed.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

748

SQL Server Data Access Components

5.13.1.9.2.4 AutoRefreshInterval Property

Used to define in what time interval in seconds the Refresh or
TCustomMSDataSet.RefreshQuick method of DataSet is called.

Class
TMSDataSetOptions

Syntaxproperty AutoRefreshInterval: integer default 60;

Remarks
Use the AutoRefreshInterval property to define in what time interval in seconds the Refresh or
TCustomMSDataSet.RefreshQuick method of DataSet is called.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.5 CheckRow Version Property

Used to determine whether dataset checks for rows modifications made by another user on
automatic generation of SQL statement for update or delete data.

Class
TMSDataSetOptions

Syntaxproperty CheckRowVersion: boolean default False;

Remarks
Use the CheckRowVersion property to determine whether dataset checks for rows
modifications made by another user on automatic generation of SQL statement for update ordelete data. If the CheckRowVersion property is False and DataSet has keyfields, the
WHERE clause of SQL statement is generated basing on these keyfields. If there is no
primary key and no Identity field, then all non-BLOB fields will take part in generating SQL
statements. If CheckRowVersion is True and DataSet has TIMESTAMP field, only this field isincluded into the WHERE clause of the generated SQL statement. Otherwise, all non-BLOB
fields are included. All mentioned fields refer to the current TMSQuery.UpdatingTable. The
default value is False.
The CheckRowVersion option requires enabled TCustomMSDataSet.Options.
© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

749

Provide Feedback

5.13.1.9.2.6 CursorUpdate Property

Used to specify the way data updates reflect on database when modifying dataset by using
server cursors ctKeySet and ctDynamic.

Class
TMSDataSetOptions

Syntaxproperty CursorUpdate: boolean default True;

Remarks
Use the CursorUpdate property to specify the way data updates reflect on database whenmodifying dataset by using server cursors ctKeySet and ctDynamic. If the CursorUpdate
property is True, all dataset modifications are passed to the database by server cursors. If the
CursorUpdate property is False, all dataset updates are passed to the server by thegenerated automatically SQL statements or specified in TCustomDADataSet.SQLUpdate,
TCustomDADataSet.SQLInsert or TCustomDADataSet.SQLDelete. The default value isTrue.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.7 DefaultValues Property

Used to enable TCustomMSDataSet to fill the DefaultExpression property of TField objects by
an appropriate value.

Class
TMSDataSetOptions

Syntaxproperty DefaultValues: boolean;

Remarks
If True, TCustomMSDataSet fills the DefaultExpression property of TField objects by an© 2019 Devart

750

SQL Server Data Access Components

appropriate value.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.8 DescribeParams Property

Used to specify whether to query TMSParam properties from the server when executing theTCustomDADataSet.Prepare method.

Class
TMSDataSetOptions

Syntaxproperty DescribeParams: boolean default False;

Remarks
Specifies whether to query TMSParam properties (Name, ParamType, DataType, Size,
TableTypeName) from the server when executing the TCustomDADataSet.Prepare method.
The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.9 DisableMultipleResults Property

Used to forbid multiple results usage by a command.

Class
TMSDataSetOptions

Syntaxproperty DisableMultipleResults: boolean default False;

Remarks
Use the DisableMultipleResults property to forbid using multiple results by a command.
Set this property to True to disable the multiple results usage. In this case, if you open a querywith a big amount of data and you have to break the execution of this query (by calling
TCustomMSDataSet.BreakExec or TDataSet.Close), the execution will be broken quickly.
The default value is False.

© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

751

Provide Feedback

5.13.1.9.2.10 DMLRefresh Property

Used to refresh a record when insertion or update is performed.

Class
TMSDataSetOptions

Syntaxproperty DMLRefresh: boolean default False;

Remarks
Use the DMLRefresh property to refresh a record when insertion or update is performed. Thisfeature doesn't support SQL Server Compact Edition. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.11 EnableBCD Property

Used to specify whether to treat numeric fields as floating-point or BCD.

Class
TMSDataSetOptions

Syntaxproperty EnableBCD: boolean;

Remarks
Use the Enable BCD property to specify whether to treat numeric fields as floating-point or
BCD. Use the EnableBCD property to specify how fields are mapped to field classes. If
EnableBCD is True, decimal and numeric fields are mapped to the TBCDField class whenfield objects are created. If EnableBCD is False, the fields are mapped to the TFloatField
class. EnableBCD determines whether numeric and decimal fields are translated as floatingpoint values or currency values. Currency values eliminate the rounding errors associatedwith the floating point math (such as a 3 * (2/3) resulting in 2.00000000001). The default value
is False.

© 2019 Devart

752

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.12 FullRefresh Property

Used to specify the fields to include in the automatically generated SQL statement whencalling the TCustomDADataSet.RefreshRecord method.

Class
TMSDataSetOptions

Syntaxproperty FullRefresh: boolean default False;

Remarks
Use the FullRefresh property to specify what fields to include in the automatically generated
SQL statement when calling the TCustomDADataSet.RefreshRecord method. If the
FullRefresh property is True, all fields from a query are included into SQL statement torefresh a single record. If FullRefresh is False, only fields from TMSQuery.UpdatingTable areincluded.
Note: If FullRefresh is True, the refresh of SQL statement for complex queries and views
may be generated with errors. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.13 HideSystemUniqueFields Property

Used to hide system fields for the prSQL, prNativeClient and prMSOLEDB providers. The
default value is True.

Class
TMSDataSetOptions

Syntaxproperty HideSystemUniqueFields: boolean default True;

Remarks
When the HideSystemUniqueFields property is set to True, system fields for the prSQL,© 2019 DevartReference

753

prNativeClient and prMSOLEDB providers are hidden in a resulting dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.14 LastIdentityValueFunction Property

Determines which system function to use to obtain an identifier when adding a record. The
default value is vfScopeIdentity.

Class
TMSDataSetOptions

Syntaxproperty LastIdentityValueFunction: TMSLastIdentityValueFunction
default vfScopeIdentity;

Remarks
Use the LastIdentityValueFunction property to determine which system function to use to
obtain an identifier when adding a record.
The possible values are:vfIdentCurrent - The IDENT_CURRENT system function is used. It returns the last identity
value generated for a specified table or view. The last identity value generated can be for any
session and any scope.
vfIdentity - The @@IDENTITY system function is used. It returns the last-inserted identity
value.
vfScopeIdentity - The SCOPE_IDENTITY system function is used. It returns the last identity
value inserted into an identity column in the same scope. A scope is a module: a stored
procedure, trigger, function, or batch.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.15 LongStrings Property

Represents string fields with the length that is greater than 255 as TStringField.

Class
TMSDataSetOptions

Syntax© 2019 Devart

754

SQL Server Data Access Components

property LongStrings: boolean;

Remarks
Represents string fields with the length that is greater than 255 as TStringField, not as
TMemoField. The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.16 NonBlocking Property

Used to fetch rows in a separate thread.

Class
TMSDataSetOptions

Syntaxproperty NonBlocking: boolean default False;

Remarks
Set the NonBlocking option to True to fetch rows in a separate thread. The BeforeFetch event
is called in the additional thread context that performs data fetching. This event is called every
time on the Fetch method call. The AfterFetch event is called in the main thread context only
once after fetching is completely finished.
In the NonBlocking mode as well as in the FetchAll=False mode an extra connection iscreated. When setting TCustomMSDataSet.Options.NonBlocking to True, you should keep inmind that execution of such queries blocks the current session. In order to avoid blocking,
OLE DB creates an additional session as in the TCustomMSDataSet.FetchAll = False mode.
It causes the same problems as in the TCustomMSDataSet.FetchAll = False mode. This
problem can be solved by using MARS (TMSConnectionOptions.MultipleActiveResultSets =True). The current session is not blocked and OLE DB is not required to create addition
session to run a query. MARS is supported since SQL Server 2005 if SQL Native Client isused as OLE DB provider.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.17 NumberRange Property

Used to set the MaxValue and MinValue properties of TIntegerField and TFloatField to© 2019 DevartReference755

appropriate values.

Class
TMSDataSetOptions

Syntaxproperty NumberRange: boolean;

Remarks
Use the NumberRange property to set the MaxValue and MinValue properties of TIntegerField
and TFloatField to appropriate values. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.18 PrepareUpdateSQL Property

Used to automatically prepare update queries before execution.

Class
TMSDataSetOptions

Syntaxproperty PrepareUpdateSQL: boolean;

Remarks
If True, update queries are automatically prepared before executing.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.19 QueryIdentity Property

Used to specify whether to request the Identity field value on execution of the Insert or Append
method.

Class
TMSDataSetOptions

Syntax© 2019 Devart

756

SQL Server Data Access Components

property QueryIdentity: boolean default True;

Remarks
Specifies whether to request the Identity field value, if such exists, on execution the Insert or
Append method. If you don't request Identity, you can have an impact on performance ofInsert or Append for about 20%. Affects only the TCustomMSDataSet.CursorType cursor. If
you insert a value into the SQL_VARIANT field and QueryIdentity is True, then EOLEDBError
raised. The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.20 QueryRecCount Property

Used to perform additional query to get record count for this SELECT, so the RecordCount
property reflects the actual number of records.

Class
TMSDataSetOptions

Syntaxproperty QueryRecCount: boolean;

Remarks
If True, and the TCustomMSDataSet.FetchAll property is False or the NonBlocking option isTrue, TCustomDADataSet performs additional query to get record count for this SELECT, so
the RecordCount property reflects the actual number of records. Does not have any effect if
the FetchAll property is True and the NonBlocking option is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.21 QuoteNames Property

Used for TCustomMSDataSet to quote all field names in autogenerated SQL statements.

Class
TMSDataSetOptions

Syntax© 2019 DevartReference757

property QuoteNames: boolean;

Remarks
If True, TCustomMSDataSet quotes all field names in autogenerated SQL statements suchas update SQL.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.22 ReflectChangeNotify Property

Indicates whether DataSet will be automatically refreshed when the underlying data on theserver is changed.

Class
TMSDataSetOptions

Syntaxproperty ReflectChangeNotify: boolean default False;

Remarks
Indicates whether DataSet will be automatically refreshed when the underlying data on theserver is changed. Automatic refresh happens when ReflectChangeNotify is True, theTCustomMSDataSet.ChangeNotification property is assigned, and the
TMSChangeNotification.OnChange parameter is nsData. This option is available only forusers of SDAC Professional Edition .

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.23 RemoveOnRefresh Property

Used for dataset to locally remove record on refresh if it does not match filter condition(WHERE clause for refresh SQL) anymore.

Class
TMSDataSetOptions

Syntaxproperty RemoveOnRefresh: boolean;© 2019 Devart

758

SQL Server Data Access Components

Remarks
When the RemoveOnRefresh property is set to True, dataset locally removes record onrefresh if it does not match filter condition (WHERE clause for refresh SQL) anymore. The
default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.24 RequiredFields Property

Used for TCustomMSDataSet to set the Required property of TField objects for the NOTNULL fields.

Class
TMSDataSetOptions

Syntaxproperty RequiredFields: boolean default False;

Remarks
If True, TCustomMSDataSet sets the Required property of TField objects for the NOT NULL
fields. It is useful when table has a trigger that updates the NOT NULL fields. The default value
is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.25 ReturnParams Property

Used to return the new values of fields to dataset after insert or update.

Class
TMSDataSetOptions

Syntaxproperty ReturnParams: boolean;

Remarks
Use the ReturnParams property to return the new values of fields to dataset after insert or© 2019 DevartReference

759

update. Actual value of a field after insert or update may be different from the value stored in
the local memory if the table has a trigger. When ReturnParams is True, OUT parameters of
the SQLInsert and SQLUpdate statements is assigned to corresponding fields. The default
value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.26 SetEmptyStrToNull Property

Force replace of empty strings with NULL values in data. Default value is False.

Class
TMSDataSetOptions

Syntaxproperty SetEmptyStrToNull: boolean;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.27 StrictUpdate Property

Used for TCustomDADataSet to raise an exception when the number of updated or deleted
records is not equal 1.

Class
TMSDataSetOptions

Syntaxproperty StrictUpdate: boolean;

Remarks
TCustomDADataSet raises an exception when the number of updated or deleted records is
not equal 1. Setting this option also causes an exception if the RefreshRecord procedure
returns more than one record. Does not affect TCustomMSDataSet.CursorType if
CursorUpdate is True. The default value is True. In order for this option to work correctly, theSQL Server NOCOUNT option should be OFF (this is the default value). If NOCOUNT is ON,
SQL Server returns 0 instead of the actual affected rows count. SDAC does not care for thisoption itself in order to avoid additional round trips to server.

© 2019 Devart

760

SQL Server Data Access Components

We do not recommend using the StrictUpdate option with tables on which a trigger is defined,
because this will cause problems if there are commands that modify data in the trigger. But if
you need to use this combination, you should call the SET NOCOUNT ON command at thevery beginning of the trigger to suppress sending affected rows count for SQL statements
executed within the trigger.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.28 TrimFixedChar Property

Used to specify whether to discard all trailing spaces in the fixed-length string fields of adataset.

Class
TMSDataSetOptions

Syntaxproperty TrimFixedChar: boolean;

Remarks
Use the TrimFixedChar property to specify whether to discard all trailing spaces in the fixedlength string fields of a dataset. The default value is True.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.29 TrimVarChar Property

Used to specify whether to discard all trailing spaces in the variable-length string fields of adataset.

Class
TMSDataSetOptions

Syntaxproperty TrimVarChar: boolean;

Remarks
Use the TrimVarChar property to specify whether to discard all trailing spaces in the variable-© 2019 DevartReference761

length string fields of a dataset. The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.9.2.30 UniqueRecords Property

Used to specify whether to query additional keyfields from the server.

Class
TMSDataSetOptions

Syntaxproperty UniqueRecords: boolean default True;

Remarks
Use the UniqueRecords property to specify whether to query additional keyfields from theserver. If UniqueRecords is False, keyfields aren't queried from the server when they are notincluded in the query explicitly. For example, the result of the query execution "SELECT
ShipName FROM Orders" holds the only field - ShipName. When used with theTCustomDADataSet.ReadOnly property set to True, the UniqueRecords option gives
insignificant advantage of performance. But in this case SQLRefresh will be generated insimplified way. If UniqueRecord is True, keyfields needed for the complete automatic
generation of SQLInsert, SQLUpdate, SQLDelete or SQLRefresh statements are queried
from the server implicitly. For example, the result of query execution "SELECT ShipName
FROM Orders" holds at least two fields - ShipName and OrderID. The default value is False.
Has effect only for the TCustomMSDataSet.CursorType cursor.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.10 TMSDataSource ClassTMSDataSource provides an interface between a SDAC dataset components and data-aware
controls on a form.
For a list of all members of this type, see TMSDataSource members.

Unit
MSAccess

Syntax© 2019 Devart

762

SQL Server Data Access Components

TMSDataSource = class(TCRDataSource);

Remarks
TMSDataSource provides an interface between a SDAC dataset components and data-aware
controls on a form.
TMSDataSource inherits its functionality directly from the TDataSource component.
At design-time assign individual data-aware components' DataSource properties from theirdrop-down listboxes.

Inheritance Hierarchy
TCRDataSource
TMSDataSource© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

DAC Forum

Provide Feedback

5.13.1.10.1 Members

TMSDataSource class overview.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.13.1.11 TMSEncryptor Class

The class that performs encrypting and decrypting of data.
For a list of all members of this type, see TMSEncryptor members.

Unit
MSAccess

SyntaxTMSEncryptor = class(TCREncryptor);

Inheritance Hierarchy
TCREncryptor
TMSEncryptor© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference763

5.13.1.11.1 Members

TMSEncryptor class overview.

Properties
Name
DataHeader (inherited from TCREncryptor)

EncryptionAlgorithm (inherited from TCREncryptor)
HashAlgorithm (inherited from TCREncryptor)
InvalidHashAction (inherited from TCREncryptor)

Password (inherited from TCREncryptor)

Description
Specifies whether the
additional information isstored with the encrypteddata.
Specifies the algorithm ofdata encryption.
Specifies the algorithm ofgenerating hash data.
Specifies the action to
perform on data fetchingwhen hash data is invalid.
Used to set a password thatis used to generate a key forencryption.

Methods
Name

Description
Sets a key, using which datais encrypted.

SetKey (inherited from TCREncryptor)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.13.1.12 TMSFileStream ClassA class for managing FILESTREAM data using Win32 API.
For a list of all members of this type, see TMSFileStream members.

Unit
MSAccess

SyntaxTMSFileStream = class(TStream);

Remarks© 2019 Devart

Provide Feedback

764

SQL Server Data Access Components

Use the TMSFileStream class to manage FILESTREAM data using Win32 API. This classinherits almost all its functionality from the TStream class, except the Close method. It's
necessary to call the Close method before the transaction commits or rolls back
FILESTREAM data.

See Also
TCustomMSDataSet.GetFileStreamForField© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.12.1 Members

TMSFileStream class overview.

Methods
Name

Description
Used to close an opened filehandle associated withFILESTREAM data.
Used to write all buffereddata to the file associatedwith FILESTREAM data.

Close

Flush
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.12.2 Methods

Methods of the TMSFileStream class.
For a complete list of the TMSFileStream class members, see the TMSFileStream Members
topic.

Public
Name
Close

Flush

Description
Used to close an opened filehandle associated withFILESTREAM data.
Used to write all buffereddata to the file associatedwith FILESTREAM data.

© 2019 DevartReference

765

See Also
TMSFileStream ClassTMSFileStream Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.12.2.1 Close Method

Used to close an opened file handle associated with FILESTREAM data.

Class
TMSFileStream

Syntax
procedure Close;

Remarks
Closes an opened file handle associated with FILESTREAM data. It's necessary to call thismethod before the transaction commits or rolls back FILESTREAM data. Failing to close thehandle will cause server-side resource leaks.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.12.2.2 Flush Method

Used to write all buffered data to the file associated with FILESTREAM data.

Class
TMSFileStream

Syntax
procedure Flush;

Remarks
Writes all buffered data to the file associated with FILESTREAM data. To use this method,
you should create TMSFileStream with access rights for writing.

© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

766

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.13 TMSMetadata Class

A component for obtaining metainformation about database objects from the server.
For a list of all members of this type, see TMSMetadata members.

Unit
MSAccess

SyntaxTMSMetadata = class(TDAMetaData);

Remarks
The TMSMetaData component is used to obtain metainformation from the server about
objects in the database, such as tables, table columns, stored procedures, etc in the form ofa table. TMSMetaData publishes properties of TDAMetaData.
To get the information you are interested in, you should initially select the proper object type in
the TMSMetadata.ObjectType property. After that you may open TMSMetadata and view theresult like in usual dataset (in the DB-aware controls or from code). This dataset may be too
big for viewing because information about all objects of the specified type is shown. To get the
information only about objects you are interested in, you should specify appropriate filters inproperties like DatabaseName, SchemaName, TableName, etc. To ascertain which
properties are applicable to the selected object type, refer to the table given in the descriptionof the ObjectType property.

ExampleHere is a small example demonstrating obtaining information about default column values of atable.
procedure TForm.ButtonClick(Sender: TObject);var
FieldNameCol, FieldDefCol: TField;
DefValue: string;
begin
MSMetadata.ObjectType := otColumns;
MSMetadata.DatabaseName := EditDatabaseName.Text;
MSMetadata.TableName := EditTableName.Text;
MSMetadata.Open;FieldNameCol := MSMetadata.FieldByName('COLUMN_NAME');
FieldDefCol := MSMetadata.FieldByName('COLUMN_DEFAULT');
Memo.Lines.Clear;
if MSMetadata.RecordCount = 0 then
© 2019 DevartReference

767

Memo.Lines.Add('Specified object not found')else
while not MSMetadata.Eof do begin
if FieldDefCol.IsNull then
DefValue := '> Not defined <'else
DefValue := FieldDefCol.AsString;Memo.Lines.Add(Format('Field Name: %s;
Default Value: %s', [FieldNa
MSMetadata.Next;
end;
end;

Inheritance Hierarchy
TMemDataSet
TDAMetaData
TMSMetadata

See Also
TCustomDADataSet.Debug
TCustomDASQL.Debug
DBMonitor
TCustomMSDataSet
TDAMetaData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.1 Members

TMSMetadata class overview.

Properties
Name
AssemblyID

AssemblyName© 2019 Devart

Description
Used to specify theassembly ID that constitutes
object type descriptor used
to retrieve metadata
information from the server.
Used to specify theassembly name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.

768

SQL Server Data Access Components

CachedUpdates (inherited from TMemDataSet)

ColumnName

Connection (inherited from TDAMetaData)

ConstraintName

DatabaseName

IndexFieldNames (inherited from TMemDataSet)

IndexName

KeyExclusive (inherited from TMemDataSet)

LinkedServer

LocalConstraints (inherited from TMemDataSet)

Used to enable or disable
the use of cached updates
for a dataset.
Used to specify the column
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify aconnection object to use toconnect to a data store.
Used to specify theconstraint name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the
database name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to get or set the list offields on which the recordset
is sorted.
Used to specify the index
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Specifies the upper andlower boundaries for arange.
Used to specify the server
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.

© 2019 DevartReference

LocalUpdate (inherited from TMemDataSet)
MetaDataKind (inherited from TDAMetaData)

ObjectType

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

ReferencedAssemblyID

Restrictions (inherited from TDAMetaData)

SchemaCollectionName

SchemaName

StoredProcName

TableName© 2019 Devart

769

Used to prevent implicit
update of rows on databaseserver.
Used to specify which kindof metainformation to show.
Used to specify the object
type metadata information
will be requested from theserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to specify thereferenced assembly ID that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to provide one or moreconditions restricting the listof objects to be described.
Used to specify the XML
schema collection name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the schemaname that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify the stored
procedure name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the tablename that constitutes object
type descriptor used toretrieve metadata
information from the server.

770

SQL Server Data Access Components

TargetNamespaceURI

UDTNameUpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Used to specify the XML
schema collection name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the UserDefined Type name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
© 2019 DevartReference

GetBlob (inherited from TMemDataSet)

GetMetaDataKinds (inherited from TDAMetaData)

GetRestrictions (inherited from TDAMetaData)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)© 2019 Devart

771

Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Used to get values
acceptable in the
MetaDataKind property.
Used to find out which
restrictions are applicable toa certain MetaDataKind.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values

772

SQL Server Data Access Components

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.13.2 Properties

Properties of the TMSMetadata class.
For a complete list of the TMSMetadata class members, see the TMSMetadata Members
topic.

PublicName
CachedUpdates (inherited from TMemDataSet)

Description
Used to enable or disable
the use of cached updates
for a dataset.

© 2019 DevartReference

Connection (inherited from TDAMetaData)

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)
MetaDataKind (inherited from TDAMetaData)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
Restrictions (inherited from TDAMetaData)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

773

Used to specify aconnection object to use toconnect to a data store.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to specify which kindof metainformation to show.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to provide one or moreconditions restricting the listof objects to be described.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Published
Name
AssemblyID

AssemblyName© 2019 Devart

Description
Used to specify theassembly ID that constitutes
object type descriptor used
to retrieve metadata
information from the server.
Used to specify theassembly name that

774

SQL Server Data Access Components

ColumnName

ConstraintName

DatabaseName

IndexName

LinkedServer

ObjectType

ReferencedAssemblyID

SchemaCollectionName

constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the column
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify theconstraint name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the
database name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the index
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify the server
name that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify the object
type metadata information
will be requested from theserver.
Used to specify thereferenced assembly ID that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the XML
schema collection name that
constitutes object typedescriptor used to retrieve© 2019 DevartReference775

metadata information fromthe server.
Used to specify the schemaname that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify the stored
procedure name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the tablename that constitutes object
type descriptor used toretrieve metadata
information from the server.
Used to specify the XML
schema collection name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.
Used to specify the UserDefined Type name that
constitutes object typedescriptor used to retrieve
metadata information fromthe server.

SchemaName

StoredProcName

TableName

TargetNamespaceURI

UDTNameSee Also
TMSMetadata Class
TMSMetadata Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.1 AssemblyID Property

Used to specify the assembly ID that constitutes object type descriptor used to retrieve
metadata information from the server.

Class© 2019 Devart

776

SQL Server Data Access Components

TMSMetadata

Syntaxproperty AssemblyID: integer default 0;

Remarks
Use the AssemblyID property to specify the ID of the assembly which together with
AssemblyName, schema, database and/or other optional names constitutes object typedescriptor that is used to retrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
AssemblyName
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.2 AssemblyName Property

Used to specify the assembly name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty AssemblyName: string;

Remarks
Use the AssemblyName property to specify the name of the assembly which together with© 2019 DevartReference

777

AssemblyID, schema, database and/or other optional names constitutes object typedescriptor that is used to retrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
AssemblyID
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.3 ColumnName Property

Used to specify the column name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty ColumnName: string;

Remarks
Use the ColumnName property to specify the column name which together with table,
schema and database names constitutes object type descriptor that is used to retrieve
metadata information from the server.
Refer to ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName© 2019 Devart

778

SQL Server Data Access Components

SchemaName
TableName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.4 ConstraintName Property

Used to specify the constraint name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty ConstraintName: string;

Remarks
Use the ConstraintName property to specify the constraint name which together with table,
schema and database names constitutes object type descriptor that is used to retrieve
metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
TableName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.5 DatabaseName Property

Used to specify the database name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata© 2019 DevartReference

779

Syntaxproperty DatabaseName: string;

Remarks
Use the DatabaseName property to specify the database name which together with table,
schema and/or other optional names constitutes object type descriptor that is used to retrieve
metadata information from the server.
Refer to ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
SchemaName
TableNameStoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.6 IndexName Property

Used to specify the index name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty IndexName: string;

Remarks
Use the IndexName property to specify the index name which together with table, schemaand database names constitutes object type descriptor that is used to retrieve metadata
information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which this© 2019 Devart

780

SQL Server Data Access Components

property is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
TableName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.7 LinkedServer Property

Used to specify the server name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty LinkedServer: string;

Remarks
Use the LinkedServer property to specify the name of the server which together with otheroptional names constitutes object type descriptor that is used to retrieve metadata informationfrom the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

781

Reserved.
5.13.1.13.2.8 ObjectType Property

Used to specify the object type metadata information will be requested from the server.

Class
TMSMetadata

Syntaxproperty ObjectType: TMSObjectType default otDatabases;

Remarks
Use the ObjectType property to specify the object type which metadata will be requested fromthe server.
The following table lists the names of applicable restriction properties for each object type andalso equivalent schema rowset name as it's described in Microsoft's MSDN OLE DB Library(see oledb.chm file for the in-depth information on each object type).

See Also
DatabaseName
SchemaName
TableNameStoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.9 ReferencedAssemblyID Property

Used to specify the referenced assembly ID that constitutes object type descriptor used toretrieve metadata information from the server.

Class
TMSMetadata

Syntax© 2019 Devart

782

SQL Server Data Access Components

property ReferencedAssemblyID: integer default 0;

Remarks
Use the ReferencedAssemblyID property to specify the ID of the referenced assembly which
together with AssemblyName, AssemblyID, schema, database and/or other optional names
constitutes object type descriptor that is used to retrieve metadata information from theserver.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
AssemblyName
AssemblyID
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.10 SchemaCollectionName Property

Used to specify the XML schema collection name that constitutes object type descriptor used
to retrieve metadata information from the server.

Class
TMSMetadata

Syntaxproperty SchemaCollectionName: string;

Remarks
Use the SchemaCollectionName property to specify the name of the XML schema collection
which together with schema and database names and/or other optional names constitutes© 2019 DevartReference

783

object type descriptor that is used to retrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName
TargetNamespaceURI© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.11 SchemaName Property

Used to specify the schema name that constitutes object type descriptor used to retrieve
metadata information from the server.

Class
TMSMetadata

Syntaxproperty SchemaName: string;

Remarks
Use the SchemaName property to specify the schema name which together with table,
database and/or other optional names constitutes object type descriptor that is used toretrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName© 2019 Devart

784

SQL Server Data Access Components

TableNameStoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.12 StoredProcName Property

Used to specify the stored procedure name that constitutes object type descriptor used toretrieve metadata information from the server.

Class
TMSMetadata

Syntaxproperty StoredProcName: string;

Remarks
Use the StoredProcName property to specify the stored procedure name which together withtable, schema and database names constitutes object type descriptor that is used to retrieve
metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
TableName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.13 TableName Property

Used to specify the table name that constitutes object type descriptor used to retrieve
metadata information from the server.

© 2019 DevartReference

785

Class
TMSMetadata

Syntaxproperty TableName: string;

Remarks
Use the TableName property to specify the table name which together with schema,
database and/or other optional names constitutes object type descriptor that is used toretrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.14 TargetNamespaceURI Property

Used to specify the XML schema collection name that constitutes object type descriptor used
to retrieve metadata information from the server.

Class
TMSMetadata

Syntaxproperty TargetNamespaceURI: string;

Remarks© 2019 Devart

786

SQL Server Data Access Components

Use the TargetNamespaceURI property to specify the name of the XML schema collection
which together with schema and database names and/or other optional names constitutes
object type descriptor that is used to retrieve metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType
DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName
SchemaCollectionName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.13.2.15 UDTName Property

Used to specify the User-Defined Type name that constitutes object type descriptor used toretrieve metadata information from the server.

Class
TMSMetadata

Syntaxproperty UDTName: string;

Remarks
Use the UDTName property to specify the name of the User-Defined Type which together
with schema and database names constitutes object type descriptor that is used to retrieve
metadata information from the server.
Refer to the ObjectType property to get the complete listing of all object types to which thisproperty is applicable. In all other cases this property is merely ignored.

See Also
ObjectType© 2019 DevartReference

787

DatabaseName
SchemaName
StoredProcName
ColumnName
IndexName
ConstraintName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.14 TMSParam ClassA class that is used to set the values of individual parameters passed with queries or stored
procedures.
For a list of all members of this type, see TMSParam members.

Unit
MSAccess

SyntaxTMSParam = class(TDAParam);

Remarks
Use the properties of TMSParam to set the value of a parameter. Objects that use
parameters create TMSParam objects to represent these parameters. For example,
TMSParam objects are used by TMSSQL, TCustomMSDataSet.
TMSParam shares many properties with TField, as both describe the value of a field in adataset. However, a TField object has several properties to describe the field binding, andhow the field is displayed, edited, or calculated that are not needed in a TMSParam object.
Conversely, TMSParam includes properties that indicate how the field value is passed as aparameter.

Inheritance Hierarchy
TDAParam
TMSParam© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

788

SQL Server Data Access Components

5.13.1.14.1 Members

TMSParam class overview.

Properties
Name
AsBlob (inherited from TDAParam)

AsBlobRef (inherited from TDAParam)

AsFloat (inherited from TDAParam)
AsInteger (inherited from TDAParam)

AsLargeInt (inherited from TDAParam)

AsMemo (inherited from TDAParam)

AsMemoRef (inherited from TDAParam)

AsSQLTimeStamp (inherited from TDAParam)

AsString (inherited from TDAParam)
AsTableAsWideString (inherited from TDAParam)
DataType (inherited from TDAParam)
IsNull (inherited from TDAParam)

Description
Used to set and read thevalue of the BLOB
parameter as string.
Used to set and read thevalue of the BLOB
parameter as a TBlob
object.
Used to assign the value fora float field to a parameter.
Used to assign the value for
an integer field to theparameter.
Used to assign the value fora LargeInteger field to theparameter.
Used to assign the value fora memo field to theparameter.
Used to set and read thevalue of the memo
parameter as a TBlob
object.
Used to specify the value ofthe parameter when it
represents a SQL
timestamp field.
Used to assign the stringvalue to the parameter.
Used to assign a recordset
to the Table-Valued
Parameter.
Used to assign the Unicode
string value to theparameter.
Indicates the data type of theparameter.
Used to indicate whether thevalue assigned to a
© 2019 DevartReference789

parameter is NULL.
Used to indicate the type ofuse for a parameter.
Specifies the size of a string
type parameter.
Used to indicate the table
type name of a TableValued Parameter.
Used to represent the valueof the parameter as Variant.

ParamType (inherited from TDAParam)
Size (inherited from TDAParam)
TableTypeName
Value (inherited from TDAParam)

Methods
Name
AssignField (inherited from TDAParam)
AssignFieldValue (inherited from TDAParam)

LoadFromFile (inherited from TDAParam)

LoadFromStream (inherited from TDAParam)

SetBlobData (inherited from TDAParam)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Assigns field name and fieldvalue to a param.
Assigns the specified field
properties and value to aparameter.
Places the content of a
specified file into a
TDAParam object.
Places the content from astream into a TDAParamobject.
Overloaded. Writes the datafrom a specified buffer to
BLOB.
Provide Feedback

5.13.1.14.2 Properties

Properties of the TMSParam class.
For a complete list of the TMSParam class members, see the TMSParam Members topic.

PublicName
AsBlob (inherited from TDAParam)© 2019 Devart

Description
Used to set and read thevalue of the BLOB
parameter as string.

790

SQL Server Data Access Components

AsBlobRef (inherited from TDAParam)

AsFloat (inherited from TDAParam)
AsInteger (inherited from TDAParam)

AsLargeInt (inherited from TDAParam)

AsMemo (inherited from TDAParam)

AsMemoRef (inherited from TDAParam)

AsSQLTimeStamp (inherited from TDAParam)

AsString (inherited from TDAParam)
AsTableAsWideString (inherited from TDAParam)

IsNull (inherited from TDAParam)

TableTypeName

Used to set and read thevalue of the BLOB
parameter as a TBlob
object.
Used to assign the value fora float field to a parameter.
Used to assign the value for
an integer field to theparameter.
Used to assign the value fora LargeInteger field to theparameter.
Used to assign the value fora memo field to theparameter.
Used to set and read thevalue of the memo
parameter as a TBlob
object.
Used to specify the value ofthe parameter when it
represents a SQL
timestamp field.
Used to assign the stringvalue to the parameter.
Used to assign a recordset
to the Table-Valued
Parameter.
Used to assign the Unicode
string value to theparameter.
Used to indicate whether thevalue assigned to aparameter is NULL.
Used to indicate the table
type name of a TableValued Parameter.

Published
Name
DataType (inherited from TDAParam)

Description
Indicates the data type of theparameter.

© 2019 DevartReference

791

Used to indicate the type ofuse for a parameter.
Specifies the size of a string
type parameter.
Used to represent the valueof the parameter as Variant.

ParamType (inherited from TDAParam)
Size (inherited from TDAParam)
Value (inherited from TDAParam)

See Also
TMSParam ClassTMSParam Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.14.2.1 AsTable Property

Used to assign a recordset to the Table-Valued Parameter.

Class
TMSParam

Syntaxproperty AsTable: TMSSQLTableObject;

Remarks
Use the AsTable property to assign a recordset to the Table-Valued Parameter. Setting
AsTable will set the DataType property to ftDataSet.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.13.1.14.2.2 TableTypeName Property

Used to indicate the table type name of a Table-Valued Parameter.

Class
TMSParam

Syntaxproperty TableTypeName: string;© 2019 Devart

Provide Feedback

792

SQL Server Data Access Components

Remarks
Use the TableTypeName property to determine the table type name of a Table-Valued
Parameter.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.15 TMSParams Class

Used to control TMSParam objects.
For a list of all members of this type, see TMSParams members.

Unit
MSAccess

SyntaxTMSParams = class(TDAParams);

Remarks
Use TMSParams to manage a list of TMSParam objects for an object that uses fieldparameters. For example, TMSStoredProc objects and TMSQuery objects use TMSParams
objects to create and access their parameters.

Inheritance Hierarchy
TDAParams
TMSParams

See Also
TMSParam
TCustomDASQL.Params
TCustomDADataSet.Params© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.15.1 Members

TMSParams class overview.

Properties© 2019 DevartReference

Name

793

Description
Used to interate through allparameters.

Items (inherited from TDAParams)

Methods
Name
FindParam (inherited from TDAParams)
ParamByName (inherited from TDAParams)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Searches for a parameterwith the specified name.
Searches for a parameterwith the specified name.
Provide Feedback

5.13.1.16 TMSQuery Class

A component for executing queries and operating record sets. It also provides flexible way to
update data.
For a list of all members of this type, see TMSQuery members.

Unit
MSAccess

SyntaxTMSQuery = class(TCustomMSDataSet);

Remarks
TMSQuery is a direct descendant of the TCustomMSDataSet component. It publishes mostof its inherited properties and events so that they can be manipulated at design-time.
Use TMSQuery to perform fetching, insertion, deletion and update of record by dynamicallygenerated SQL statements. TMSQuery provides automatic blocking of records, their
checking before edit and refreshing after post. Set SQL, SQLInsert, SQLDelete, SQLRefresh,and SQLUpdate properties to define SQL statements for subsequent accesses to the
database server. There is no restriction to their syntax, so any SQL statement is allowed.
Usually you need to use INSERT, DELETE, and UPDATE statements but you also may use
stored procedures in more diverse cases.
To modify records, you can specify KeyFields. If they are not specified, TMSQuery will
retrieve primary keys for UpdatingTable from metadata. TMSQuery can automatically update© 2019 Devart

794

SQL Server Data Access Components

only one table. Updating table is defined by the UpdatingTable property if this property is set.
Otherwise, the table a field of which is the first field in the field list in the SELECT clause isused as an updating table.
The SQLInsert, SQLDelete, SQLUpdate, SQLRefresh properties support automatic binding ofparameters which have identical names to fields captions. To retrieve the value of a field as it
was before the operation use the field name with the 'OLD_' prefix. This is especially usefulwhen doing field comparisons in the WHERE clause of the statement. Use theTCustomDADataSet.BeforeUpdateExecute event to assign the value to additional parameters
and the TCustomDADataSet.AfterUpdateExecute event to read them.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet
TMSQuerySee Also
Updating Data with SDAC Dataset Components
Master/Detail Relationships
TMSStoredProc
TMSTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.16.1 Members

TMSQuery class overview.

Properties
Name
BaseSQL (inherited from TCustomDADataSet)

CachedUpdates (inherited from TMemDataSet)

Description
Used to return SQL text
without any changes
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
the use of cached updates
for a dataset.

ChangeNotification (inherited from TCustomMSDataSet) Points to a
TMSChangeNotification© 2019 DevartReference795

component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
Disconnected (inherited from TCustomDADataSet)
opened after connection isclosed.
Used to specify encryption
Encryption (inherited from TCustomMSDataSet)
options in a dataset.
Defines whether to request
all records of the query from
FetchAll
database server when thedataset is being opened.
Used to define the numberof rows to be transferred
FetchRows (inherited from TCustomDADataSet)
across the network at thesame time.
Used to change the WHERE
clause of SELECT
FilterSQL (inherited from TCustomDADataSet)
statement and reopen aquery.
FinalSQL (inherited from TCustomDADataSet)© 2019 Devart

Used to return SQL text withall changes performed by

796

SQL Server Data Access Components

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

LockMode
MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to specify what kind oflock will be performed when
editing a record.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.

© 2019 DevartReference

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)© 2019 Devart

797

Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.

798

SQL Server Data Access Components

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

UpdatingTable

Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.
Used to specify which table
in a query is assumed to be
the target for subsequentdata-modification queries asa result of user incentive toinsert, update or delete
records.

Methods
Name
AddWhere (inherited from TCustomDADataSet)

Description
Adds condition to the© 2019 DevartReference

799

WHERE clause of SELECT
statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clausefrom the SQL property and
DeleteWhere (inherited from TCustomDADataSet)
assigns the BaseSQL
property.
Enables changing the
EditRangeEnd (inherited from TMemDataSet)
ending value for an existing
range.
Enables changing the
EditRangeStart (inherited from TMemDataSet)
starting value for an existing
range.
Overloaded. Executes a
Execute (inherited from TCustomDADataSet)
SQL statement on theserver.
Indicates whether SQL
Executing (inherited from TCustomDADataSet)
statement is still being
executed.
Fetched (inherited from TCustomDADataSet)© 2019 Devart

Used to learn whether
TCustomDADataSet has

800

SQL Server Data Access Components

already fetched all rows.
Used to learn whether
Fetching (inherited from TCustomDADataSet)
TCustomDADataSet is still
fetching rows.
Used to learn whether
FetchingAll (inherited from TCustomDADataSet)
TCustomDADataSet isfetching all rows to the end.
Searches for a record which
FindKey (inherited from TCustomDADataSet)
contains specified fieldvalues.
Description is not available
FindMacro (inherited from TCustomDADataSet)at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset that
FindNearest (inherited from TCustomDADataSet)
matches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether a
FindParam (inherited from TCustomMSDataSet)
parameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
GetBlob (inherited from TMemDataSet)
current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
TCustomDADataSet)

key field names.

GetOrderBy (inherited from TCustomDADataSet)

Retrieves an ORDER BY
clause from a SQL© 2019 DevartReference

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)
SaveSQL (inherited from TCustomDADataSet)© 2019 Devart

801statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property

802

SQL Server Data Access Components

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName

Description

AfterExecute (inherited from TCustomDADataSet)

Occurs after a component© 2019 DevartReference

AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute (inherited fromTCustomMSDataSet)
BeforeFetch (inherited from TCustomDADataSet)
BeforeUpdateExecute (inherited fromTCustomMSDataSet)
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum803

has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.16.2 Properties

Properties of the TMSQuery class.
For a complete list of the TMSQuery class members, see the TMSQuery Members topic.

PublicName

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
CommandTimeout (inherited from TCustomMSDataSet) Used to specify the wait time
before terminating the© 2019 Devart

804

SQL Server Data Access Components

Conditions (inherited from TCustomDADataSet)

Connection (inherited from TCustomMSDataSet)

CursorType (inherited from TCustomMSDataSet)
DataTypeMap (inherited from TCustomDADataSet)

Debug (inherited from TCustomDADataSet)

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption (inherited from TCustomMSDataSet)

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)

attempt to execute acommand and generating anerror.
Used to add WHERE
conditions to a query
Used to specify aconnection object that will be
used to connect to a datastore.
Cursor types supported by
SQL Server.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL© 2019 DevartReference

KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)© 2019 Devart

805

statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.

806

SQL Server Data Access Components

Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling the© 2019 DevartReference

SQLUpdate (inherited from TCustomDADataSet)

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

807

TCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Published
Name
FetchAll

LockModeUpdatingTable

See Also
TMSQuery ClassTMSQuery Class Members© 2019 Devart

Description
Defines whether to request
all records of the query fromdatabase server when thedataset is being opened.
Used to specify what kind oflock will be performed when
editing a record.
Used to specify which table
in a query is assumed to be
the target for subsequentdata-modification queries asa result of user incentive toinsert, update or delete
records.

808

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.16.2.1 FetchAll Property

Defines whether to request all records of the query from database server when the dataset isbeing opened.

Class
TMSQuery

Syntaxproperty FetchAll: boolean;

Remarks
When set to True, all records of the query are requested from database server when thedataset is being opened. When set to False, records are retrieved when a data-aware
component or a program requests it. If a query can return a lot of records, set this property to
False if initial response time is important.
When the FetchAll property is False, the first call to TMemDataSet.Locate and
TMemDataSet.LocateEx methods may take a lot of time to retrieve additional records to theclient side.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.16.2.2 LockMode Property

Used to specify what kind of lock will be performed when editing a record.

Class
TMSQuery

Syntaxproperty LockMode: TLockMode;

Remarks
Use the LockMode property to define what kind of lock will be performed when editing arecord. Locking a record is useful in creating multi-user applications. It prevents modification© 2019 DevartReference809

of a record by several users at the same time.
Locking is performed by the RefreshRecord method.
The default value is lmNone.

See Also
TMSStoredProc.LockMode
TMSTable.LockMode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.16.2.3 UpdatingTable Property

Used to specify which table in a query is assumed to be the target for subsequent datamodification queries as a result of user incentive to insert, update or delete records.

Class
TMSQuery

Syntaxproperty UpdatingTable: string;

Remarks
Use the UpdatingTable property to specify which table in a query is assumed to be the target
for the subsequent data-modification queries as a result of user incentive to insert, update ordelete records.
This property is used on Insert, Update, Delete or RefreshRecord (see also
TCustomMSDataSet.Options) if appropriate SQL (SQLInsert, SQLUpdate or SQLDelete) is
not provided.
If UpdatingTable is not set then the first table used in a query is assumed to be the target.
All fields from other than target table have their ReadOnly properties set to True (ifTCustomMSDataSet.Options )With TCustomMSDataSet.CursorType UpdatingTable can be used only if
TCustomMSDataSet.Options = False.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

810

SQL Server Data Access Components

5.13.1.17 TMSSQL Class

A component for executing SQL statements and calling stored procedures on the databaseserver.
For a list of all members of this type, see TMSSQL members.

Unit
MSAccess

SyntaxTMSSQL = class(TCustomDASQL);

Remarks
The TMSSQL component is a direct descendant of the TCustomDASQL class.
Use The TMSSQL component when a client application must execute SQL statement or the
PL/SQL block, and call stored procedure on the database server. The SQL statement should
not retrieve rows from the database.

Inheritance Hierarchy
TCustomDASQLTMSSQLSee Also
TMSQuery© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.1 Members

TMSSQL class overview.

Properties
Name
ChangeCursor (inherited from TCustomDASQL)

Description
Enables or disables
changing screen cursor
when executing commandsin the NonBlocking mode.

CommandTimeout

Used to specify the wait time
before terminating the© 2019 DevartReference

Connection

Debug (inherited from TCustomDASQL)

DescribeParams

FinalSQL (inherited from TCustomDASQL)

MacroCount (inherited from TCustomDASQL)
Macros (inherited from TCustomDASQL)
NonBlocking

ParamCheck (inherited from TCustomDASQL)

ParamCount (inherited from TCustomDASQL)
ParamsParamValues (inherited from TCustomDASQL)

PermitPrepare© 2019 Devart

811

attempt to execute acommand and generating anerror.
Used to specify aconnection object that will be
used to connect to a datastore.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify whether toquery TMSParam properties
from the server when
executing theTCustomDASQL.Prepare
method.
Used to return a SQL
statement with expanded
macros.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to execute a SQL
statement in a separate
thread.
Used to specify whether
parameters for the Params
property are implicitly
generated when the SQL
property is being changed.
Indicates the number ofparameters in the Params
property.
Contains parameters for aquery's SQL statement.
Used to get or set the valuesof individual fieldparameters that are
identified by name.
This option is not supported
any more.

812

SQL Server Data Access Components

Prepared (inherited from TCustomDASQL)

RowsAffected (inherited from TCustomDASQL)

SQL (inherited from TCustomDASQL)

Used to indicate whether aquery is prepared forexecution.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
Used to provide a SQL
statement that a
TCustomDASQL
component executes when
the Execute method iscalled.

Methods
Name
Execute (inherited from TCustomDASQL)

ExecuteForXML

Executing (inherited from TCustomDASQL)
FindMacro (inherited from TCustomDASQL)
FindParam
MacroByName (inherited from TCustomDASQL)

ParamByName
Prepare (inherited from TCustomDASQL)

UnPrepare (inherited from TCustomDASQL)

Description
Overloaded. Executes a
SQL statement on theserver.
Overloaded. Provides data
in readable view for the
SELECT statements written
using the FOR XML clause.
Checks whether
TCustomDASQL still
executes a SQL statement.
Searches for a macro withthe specified name.
Determines if a parameterwith the specified nameexists in a dataset.
Finds a Macro with thename passed in Name.
Sets or uses parameter
information for a specificparameter based on its
name.
Allocates, opens, andparses cursor for a query.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
© 2019 DevartReference

WaitExecuting (inherited from TCustomDASQL)

813

Waits until TCustomDASQL
executes a SQL statement.

EventsName
AfterExecute (inherited from TCustomDASQL)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs after a SQL
statement has been
executed.
Provide Feedback

5.13.1.17.2 Properties

Properties of the TMSSQL class.
For a complete list of the TMSSQL class members, see the TMSSQL Members topic.

PublicName
ChangeCursor (inherited from TCustomDASQL)

Debug (inherited from TCustomDASQL)

FinalSQL (inherited from TCustomDASQL)

MacroCount (inherited from TCustomDASQL)
Macros (inherited from TCustomDASQL)

ParamCheck (inherited from TCustomDASQL)

ParamCount (inherited from TCustomDASQL)© 2019 Devart

Description
Enables or disables
changing screen cursor
when executing commandsin the NonBlocking mode.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to return a SQL
statement with expanded
macros.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify whether
parameters for the Params
property are implicitly
generated when the SQL
property is being changed.
Indicates the number ofparameters in the Params

814

SQL Server Data Access Components

ParamValues (inherited from TCustomDASQL)

Prepared (inherited from TCustomDASQL)

RowsAffected (inherited from TCustomDASQL)

SQL (inherited from TCustomDASQL)

property.
Used to get or set the valuesof individual fieldparameters that are
identified by name.
Used to indicate whether aquery is prepared forexecution.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
Used to provide a SQL
statement that a
TCustomDASQL
component executes when
the Execute method iscalled.

Published
Name
CommandTimeout

Connection

DescribeParams

NonBlocking
ParamsPermitPrepare

Description
Used to specify the wait time
before terminating theattempt to execute acommand and generating anerror.
Used to specify aconnection object that will be
used to connect to a datastore.
Used to specify whether toquery TMSParam properties
from the server when
executing theTCustomDASQL.Prepare
method.
Used to execute a SQL
statement in a separate
thread.
Contains parameters for aquery's SQL statement.
This option is not supported
any more.
© 2019 DevartReference

815

See Also
TMSSQL ClassTMSSQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.2.1 CommandTimeout Property

Used to specify the wait time before terminating the attempt to execute a command andgenerating an error.

Class
TMSSQL

Syntaxproperty CommandTimeout: integer default 0;

Remarks
The time in seconds to wait for the command to execute.
The default value is 0. The 0 value indicates no limit (an attempt to execute a command will
wait indefinitely).
If a command is successfully executed prior to the expiration of the seconds specified,
CommandTimeout has no effect. Otherwise, the 'Query timeout expired' error is generated by
SQL Server. This error has the DB_E_ABORTLIMITREACHED OLEDB error code.
For more information about OLEDB Errors, refer to http://technet.microsoft.com/en-us/library/
ms171852.aspx
Samples
DelphiMSSQL.CommandTimeout := 5; // wait 5 seconds for the command to execute
MSSQL.SQL.Text := 'long-lasting query';try
MSSQL.Execute;excepton E: EOLEDBError do begin
if E.ErrorCode = DB_E_ABORTLIMITREACHED then // the 'Query timeout expir
ShowMessage(E.Message);raise;
end;
end;
Note: To run this code, it is needed to add the OLEDBAccess and OLEDBC units to the© 2019 Devart

816

SQL Server Data Access Components

USES clause of the unit.
C++Builder
MSSQL->CommandTimeout = 5; // wait 5 seconds for the command to execute
MSSQL->SQL->Text = "long-lasting query";try{
MSSQL->Execute();}catch (EOLEDBError &E){
if (E.ErrorCode == DB_E_ABORTLIMITREACHED) // the 'Query timeout expired'
ShowMessage(E.Message);
throw;}
Note: To run this code, it is needed to include the oledberr.h header file to the unit.

See Also
TMSConnection.ConnectionTimeout© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.2.2 Connection Property

Used to specify a connection object that will be used to connect to a data store.

Class
TMSSQL

Syntaxproperty Connection: TCustomMSConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomMSConnection descendantobjects.
At runtime, set the Connection property to reference an existing object of a
TCustomMSConnection descendant.

See Also
TCustomMSConnection© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

817

Provide Feedback

5.13.1.17.2.3 DescribeParams Property

Used to specify whether to query TMSParam properties from the server when executing theTCustomDASQL.Prepare method.

Class
TMSSQL

Syntaxproperty DescribeParams: boolean default False;

Remarks
Specifies whether to query TMSParam properties (Name, ParamType, DataType, Size,
TableTypeName) from the server when executing the TCustomDASQL.Prepare method. The
default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.2.4 NonBlocking Property

Used to execute a SQL statement in a separate thread.

Class
TMSSQL

Syntaxproperty NonBlocking: boolean;

Remarks
Set the NonBlocking option to True to execute a SQL statement in a separate thread.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

818

SQL Server Data Access Components

5.13.1.17.2.5 Params Property

Contains parameters for a query's SQL statement.

Class
TMSSQL

Syntaxproperty Params: TMSParams stored False;

Remarks
Contains parameters for a query's SQL statement.
Access Params at runtime to view and set parameter names, values, and data types
dynamically (at design time use the Parameters editor to set the parameter information).
Params is a zero-based array of parameter records. Index specifies the array element toaccess.
An easier way to set and retrieve parameter values when the name of each parameter isknown is to call ParamByName.

See Also
TMSParam
ParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.2.6 PermitPrepare Property

This option is not supported any more.

Class
TMSSQL

Syntaxproperty PermitPrepare: boolean stored False;

Remarks
This option is out of date and isn't supported any more. The default behavior is the same tothat when PermitPrepare is set to False. To get the same behaviour as when PermitPrepare
is set to True, you need to execute the TCustomDASQL.Prepare method explicitly.
© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

819

Provide Feedback

5.13.1.17.3 Methods

Methods of the TMSSQL class.
For a complete list of the TMSSQL class members, see the TMSSQL Members topic.

PublicName
Execute (inherited from TCustomDASQL)

ExecuteForXML

Executing (inherited from TCustomDASQL)
FindMacro (inherited from TCustomDASQL)
FindParam
MacroByName (inherited from TCustomDASQL)

ParamByName

Prepare (inherited from TCustomDASQL)

UnPrepare (inherited from TCustomDASQL)

WaitExecuting (inherited from TCustomDASQL)

See Also
TMSSQL Class© 2019 Devart

Description
Overloaded. Executes a
SQL statement on theserver.
Overloaded. Provides data
in readable view for the
SELECT statements written
using the FOR XML clause.
Checks whether
TCustomDASQL still
executes a SQL statement.
Searches for a macro withthe specified name.
Determines if a parameterwith the specified nameexists in a dataset.
Finds a Macro with thename passed in Name.
Sets or uses parameter
information for a specificparameter based on its
name.
Allocates, opens, andparses cursor for a query.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Waits until TCustomDASQL
executes a SQL statement.

820

SQL Server Data Access Components

TMSSQL Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.3.1 ExecuteForXML Method

Provides data in readable view for the SELECT statements written using the FOR XML
clause.

Class
TMSSQL

Overload List
Name
ExecuteForXML

ExecuteForXML(out XML: string)© 1997-2019
Devart. All Rights
Reserved.

Request Support

Description
Provides data in readable view for the
SELECT statements written using the FOR
XML clause.
Provides data in readable view for the
SELECT statements written using the FOR
XML clause.
DAC Forum

Provide Feedback

Provides data in readable view for the SELECT statements written using the FOR XML
clause.

Unit
SyntaxRemarks
SQL Server returns data in a specific format when queries with the FOR XML clause areopened using the TDataSet.Open method. In order to obtain data in readable view for the
SELECT statements written using the FOR XML clause, you should use one of theseoverloaded procedures.
The TOLEDBOutputEncoding type is declared in the OLEDBAccess unit.

See Also
TCustomDASQL.Execute© 2019 DevartReference© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

821

Provide Feedback

Provides data in readable view for the SELECT statements written using the FOR XML
clause.

Class
TMSSQL

Syntax
procedure ExecuteForXML(out XML: string); overload;procedure
ExecuteForXML(out XML: string); overload;
Parameters
XML
Is an output parameter where the result of the query execution is written.

Remarks
SQL Server returns data in a specific format when queries with the FOR XML clause areopened using the TDataSet.Open method. In order to obtain data in readable view for the
SELECT statements written using the FOR XML clause, you should use one of theseoverloaded procedures.

See Also
TCustomDASQL.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.3.2 FindParam Method

Determines if a parameter with the specified name exists in a dataset.

Class
TMSSQL

Syntaxfunction FindParam(const Value: string): TMSParam;
Parameters© 2019 Devart

822

SQL Server Data Access Components

Valueholds the name of the param for which to search.
Return Valuethe TMSParam object for the specified Name. If a TMSParam object with matching namewas not found, returns nil.

Remarks
Call the FindParam method to determine if a parameter with the specified name exists in adataset. Name is the name of the param for which to search. If FindParam finds a param witha matching name, it returns a TMSParam object for the specified Name. Otherwise it returns
nil.

See Also
ParamsParamByName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.17.3.3 ParamByName Method

Sets or uses parameter information for a specific parameter based on its name.

Class
TMSSQL

Syntaxfunction ParamByName(const Value: string): TMSParam;
Parameters
Value
Holds the Parameter value.
Return Value
the parameter, if a match was found. Otherwise, an exception is raised.

Remarks
Call the ParamByName method to set or use parameter information for a specific parameterbased on its name. Name is the name of the parameter for which to retrieve information.
ParamByName is used to set the parameter's value at runtime and returns a TMSParamobject.

© 2019 DevartReference

823

ExampleFor example, the following statement retrieves the current value of a parameter called"Contact" into an edit box:
Edit1.Text := Query1.ParamsByName('Contact').AsString;See Also
TMSParam
ParamsFindParam© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.18 TMSStoredProc Class

A component for accessing and executing stored procedures and functions.
For a list of all members of this type, see TMSStoredProc members.

Unit
MSAccess

SyntaxTMSStoredProc = class(TCustomMSStoredProc);

Remarks
Use TMSStoredProc to access stored procedures on the database server.
You need only to define the StoredProcName property, and the SQL statement to call thestored procedure will be generated automatically.
Use the Execute method at runtime to generate request that instructs server to executeprocedure and return parameters in the Params property.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet
TCustomMSStoredProc
TMSStoredProc© 2019 Devart

824

SQL Server Data Access Components

See Also
TMSQuery
TMSSQL
Updating Data with SDAC Dataset Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.18.1 Members

TMSStoredProc class overview.

Properties
Name

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
© 2019 DevartReference

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption (inherited from TCustomMSDataSet)

FetchAll (inherited from TCustomMSDataSet)

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)© 2019 Devart

825

Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.

826

SQL Server Data Access Components

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

LockMode
MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to specify what kind oflock will be performed when
editing a record.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range is© 2019 DevartReference

ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)© 2019 Devart

827

applied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.

828

SQL Server Data Access Components

Used to specify the name ofthe stored procedure to callon the server.
Used if an application does
not need bidirectional
UniDirectional (inherited from TCustomDADataSet)
access to records in the
result set.
Used to point to an update
object component which
UpdateObject (inherited from TCustomMSDataSet)
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
UpdateRecordTypes (inherited from TMemDataSet)
when cached updates areenabled.
Used to check the status ofUpdatesPending (inherited from TMemDataSet)
the cached updates buffer.
Specifies which table in aquery is assumed to be thetarget for subsequent dataUpdatingTable (inherited from TCustomMSStoredProc) modification queries as aresult of user incentive toinsert, update or delete
records.
StoredProcName

Methods
Name
AddWhere (inherited from TCustomDADataSet)

ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

Description
Adds condition to the
WHERE clause of SELECT
statement in the SQL
property.
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its prior© 2019 DevartReference829

state.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clausefrom the SQL property and
DeleteWhere (inherited from TCustomDADataSet)
assigns the BaseSQL
property.
Enables changing the
EditRangeEnd (inherited from TMemDataSet)
ending value for an existing
range.
Enables changing the
EditRangeStart (inherited from TMemDataSet)
starting value for an existing
range.
Executes SQL statements
ExecProc (inherited from TCustomMSStoredProc)
on the server.
Overloaded. Executes a
Execute (inherited from TCustomDADataSet)
SQL statement on theserver.
Indicates whether SQL
Executing (inherited from TCustomDADataSet)
statement is still being
executed.
Used to learn whether
Fetched (inherited from TCustomDADataSet)
TCustomDADataSet has
already fetched all rows.
Used to learn whether
Fetching (inherited from TCustomDADataSet)
TCustomDADataSet is still
fetching rows.
Used to learn whether
FetchingAll (inherited from TCustomDADataSet)
TCustomDADataSet isfetching all rows to the end.
Searches for a record which
FindKey (inherited from TCustomDADataSet)
contains specified fieldvalues.
Description is not available
FindMacro (inherited from TCustomDADataSet)at the moment.
© 2019 Devart

830

SQL Server Data Access Components

Moves the cursor to a
specific record or to the firstrecord in the dataset that
FindNearest (inherited from TCustomDADataSet)
matches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether a
FindParam (inherited from TCustomMSDataSet)
parameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
GetBlob (inherited from TMemDataSet)
current record when only its
name or the field itself isknown.
Returns internal field types
GetDataType (inherited from TCustomDADataSet)
defined in the MemData andaccompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate© 2019 DevartReference

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)

PrepareSQL (inherited from TCustomMSStoredProc)

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)© 2019 Devart

831

method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
Builds a query for
TCustomMSStoredProc
based on the Params andStoredProcName
properties, and assign it to
the SQL property.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clause

832

SQL Server Data Access Components

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)
UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)of a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
AfterExecute (inherited from TCustomDADataSet)
AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute (inherited fromTCustomMSDataSet)

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.

© 2019 DevartReference

BeforeFetch (inherited from TCustomDADataSet)
BeforeUpdateExecute (inherited fromTCustomMSDataSet)
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

833

Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.18.2 Properties

Properties of the TMSStoredProc class.
For a complete list of the TMSStoredProc class members, see the TMSStoredProc
Members topic.

PublicName

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query© 2019 Devart

834

SQL Server Data Access Components

Connection (inherited from TCustomMSDataSet)

CursorType (inherited from TCustomMSDataSet)
DataTypeMap (inherited from TCustomDADataSet)

Debug (inherited from TCustomDADataSet)

DetailFields (inherited from TCustomDADataSet)

Disconnected (inherited from TCustomDADataSet)
Encryption (inherited from TCustomMSDataSet)

FetchAll (inherited from TCustomMSDataSet)

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)

Used to specify aconnection object that will be
used to connect to a datastore.
Cursor types supported by
SQL Server.
Used to set data typemapping rules
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the fields
that correspond to theforeign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Used to decrease the timeof retrieving additional
records to the client side
when calling
TMemDataSet.Locate and
TMemDataSet.LocateEx forthe first time.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
© 2019 DevartReference

IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)© 2019 Devart

835

Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the

836

SQL Server Data Access Components

Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record by© 2019 DevartReference

837

calling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
SQLUpdate (inherited from TCustomDADataSet)
when applying an update toa dataset.
Used if an application does
not need bidirectional
UniDirectional (inherited from TCustomDADataSet)
access to records in the
result set.
Used to point to an update
object component which
UpdateObject (inherited from TCustomMSDataSet)
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
UpdateRecordTypes (inherited from TMemDataSet)
when cached updates areenabled.
Used to check the status ofUpdatesPending (inherited from TMemDataSet)
the cached updates buffer.
Specifies which table in aquery is assumed to be thetarget for subsequent dataUpdatingTable (inherited from TCustomMSStoredProc) modification queries as aresult of user incentive toinsert, update or delete
records.

Published
Name
LockMode

StoredProcName

See Also
TMSStoredProc Class
TMSStoredProc Class Members© 2019 Devart

Description
Used to specify what kind oflock will be performed when
editing a record.
Used to specify the name ofthe stored procedure to callon the server.

838

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.18.2.1 LockMode Property

Used to specify what kind of lock will be performed when editing a record.

Class
TMSStoredProc

Syntaxproperty LockMode: TLockMode;

Remarks
Use the LockMode property to define what kind of lock will be performed when editing arecord. Locking a record is useful in creating multi-user applications. It prevents modificationof a record by several users at the same time.
Locking is performed by the RefreshRecord method.
The default value is lmNone.

See Also
TMSQuery.LockMode
TMSTable.LockMode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.18.2.2 StoredProcName Property

Used to specify the name of the stored procedure to call on the server.

Class
TMSStoredProc

Syntaxproperty StoredProcName: string;

Remarks
Use the StoredProcName property to specify the name of the stored procedure to call on the© 2019 DevartReference

839

server. If StoredProcName does not match the name of an existing stored procedure on theserver, then when the application attempts to prepare the procedure prior to execution, an
exception is raised.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19 TMSTable Class

A component for retrieving and updating data in a single table without writing SQL statements.
For a list of all members of this type, see TMSTable members.

Unit
MSAccess

SyntaxTMSTable = class(TCustomMSTable);

Remarks
The TMSTable component allows retrieving and updating data in a single table without writing
SQL statements. Use TMSTable to access data in a table or view. Use the TableName
property to specify table name. TMSTable uses the KeyFields property to build SQL
statements for updating table data. KeyFields is a string containing a semicolon-delimited listof the field names.

Inheritance Hierarchy
TMemDataSet
TCustomDADataSet
TCustomMSDataSet
TCustomMSTable
TMSTableSee Also
Updating Data with SDAC Dataset Components
Master/Detail Relationships
Performance of Obtaining Data
TCustomMSDataSet
TMSQueryTCustomMSTable© 2019 Devart

840

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19.1 Members

TMSTable class overview.

Properties
Name

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.

© 2019 DevartReference

Disconnected (inherited from TCustomDADataSet)
Encryption (inherited from TCustomMSDataSet)

FetchAll

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)© 2019 Devart

841

Used to keep dataset
opened after connection isclosed.
Used to specify encryption
options in a dataset.
Defines whether to request
all records of the query fromdatabase server when thedataset is being opened.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.

842

SQL Server Data Access Components

LockMode
MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)

MasterFields (inherited from TCustomDADataSet)

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)
OrderFields

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

Used to specify what kind oflock will be performed when
editing a record.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that areused as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to build ORDER BY
clause of SQL statements.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
© 2019 DevartReference

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

TableName

UniDirectional (inherited from TCustomDADataSet)© 2019 Devart

843

Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when
its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used to specify the name ofthe database table thiscomponent encapsulates.
Used if an application does
not need bidirectional
access to records in the
result set.

844

SQL Server Data Access Components

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name

Description
Adds condition to the
WHERE clause of SELECT
AddWhere (inherited from TCustomDADataSet)
statement in the SQL
property.
Applies a range to the
ApplyRange (inherited from TMemDataSet)
dataset.
Overloaded. Writes
ApplyUpdates (inherited from TMemDataSet)
dataset's pending cachedupdates to a database.
Removes any ranges
CancelRange (inherited from TMemDataSet)
currently in effect for adataset.
Clears all pending cachedupdates from cache andCancelUpdates (inherited from TMemDataSet)
restores dataset in its priorstate.
Clears the cached updates
CommitUpdates (inherited from TMemDataSet)buffer.
Used to obtain a stream forreading data from or writing
CreateBlobStream (inherited from TCustomDADataSet) data to a BLOB field,
specified by the Field
parameter.
Serves for the creating of a
CreateProcCall (inherited from TCustomMSDataSet)
stored procedures call.
Makes permanent changes
DeferredPost (inherited from TMemDataSet)
to the database server.
Removes WHERE clause
DeleteWhere (inherited from TCustomDADataSet)from the SQL property and© 2019 DevartReference

EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

Execute (inherited from TCustomDADataSet)

Executing (inherited from TCustomDADataSet)

Fetched (inherited from TCustomDADataSet)

Fetching (inherited from TCustomDADataSet)

FetchingAll (inherited from TCustomDADataSet)

FindKey (inherited from TCustomDADataSet)
FindMacro (inherited from TCustomDADataSet)

FindNearest (inherited from TCustomDADataSet)

FindParam (inherited from TCustomMSDataSet)

GetBlob (inherited from TMemDataSet)

GetDataType (inherited from TCustomDADataSet)© 2019 Devart

845

assigns the BaseSQL
property.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Executes a
SQL statement on theserver.
Indicates whether SQL
statement is still being
executed.
Used to learn whether
TCustomDADataSet has
already fetched all rows.
Used to learn whether
TCustomDADataSet is still
fetching rows.
Used to learn whether
TCustomDADataSet isfetching all rows to the end.
Searches for a record whichcontains specified fieldvalues.
Description is not available
at the moment.
Moves the cursor to a
specific record or to the firstrecord in the dataset thatmatches or is greater thanthe values specified in the
KeyValues parameter.
Indicates whether aparameter with the specified
name exists in a dataset.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Returns internal field types
defined in the MemData and846

SQL Server Data Access Components

accompanying modules.
Returns a multireference
GetFieldObject (inherited from TCustomDADataSet)
shared object from field.
GetFieldPrecision (inherited from TCustomDADataSet) Retrieves the precision of anumber field.
Retrieves the scale of a
GetFieldScale (inherited from TCustomDADataSet)
number field.
Used to create the
GetFileStreamForField (inherited from
TMSFileStream object for
TCustomMSDataSet)
working with FILESTREAM
data.
GetKeyFieldNames (inherited from
Provides a list of available
TCustomDADataSet)
GetOrderBy (inherited from TCustomDADataSet)

GotoCurrent (inherited from TCustomDADataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Lock (inherited from TCustomMSDataSet)
LockTable (inherited from TCustomMSDataSet)
MacroByName (inherited from TCustomDADataSet)
OpenNext (inherited from TCustomMSDataSet)
ParamByName (inherited from TCustomMSDataSet)
Prepare (inherited from TCustomDADataSet)
PrepareSQL (inherited from TCustomMSTable)

key field names.
Retrieves an ORDER BY
clause from a SQL
statement.
Sets the current record inthis dataset similar to thecurrent record in anotherdataset.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Overloaded. Locks thecurrent records to prevent
multiple users' access to it.
Locks a table to prevent
multiple access to it.
Finds a Macro with thename passed in Name.
Opens next rowset in thestatement.
Provides access to aparameter by its name.
Allocates, opens, andparses cursor for a query.
Determines KeyFields and© 2019 DevartReference

RefreshQuick (inherited from TCustomMSDataSet)

RefreshRecord (inherited from TCustomDADataSet)
RestoreSQL (inherited from TCustomDADataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveSQL (inherited from TCustomDADataSet)

SaveToXML (inherited from TMemDataSet)

SetOrderBy (inherited from TCustomDADataSet)
SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

SQLSaved (inherited from TCustomDADataSet)
UnLock (inherited from TCustomDADataSet)© 2019 Devart

847

build query ofTCustomMSTable.
An optimized procedure to
retrieve the changes applied
to the server by other clientsto the particular client side.
Actualizes field values forthe current record.
Restores the SQL property
modified by AddWhere and
SetOrderBy.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Saves the SQL property
value to BaseSQL.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Builds an ORDER BY clauseof a SELECT statement.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Determines if the SQL
property value was saved to
the BaseSQL property.
Releases a record lock.

848

SQL Server Data Access Components

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
AfterExecute (inherited from TCustomDADataSet)
AfterFetch (inherited from TCustomDADataSet)
AfterUpdateExecute (inherited fromTCustomMSDataSet)
BeforeFetch (inherited from TCustomDADataSet)
BeforeUpdateExecute (inherited fromTCustomMSDataSet)
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs after a component
has executed a query todatabase.
Occurs after dataset finishes
fetching data from server.
Occurs after executing
insert, delete, update, lockand refresh operation.
Occurs before dataset isgoing to fetch block ofrecords from the server.
Occurs before executing
insert, delete, update, lockand refresh operation.
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback© 2019 DevartReference849

5.13.1.19.2 Properties

Properties of the TMSTable class.
For a complete list of the TMSTable class members, see the TMSTable Members topic.

PublicName

Description
Used to return SQL text
without any changes
BaseSQL (inherited from TCustomDADataSet)
performed by AddWhere,
SetOrderBy, and FilterSQL.
Used to enable or disable
CachedUpdates (inherited from TMemDataSet)
the use of cached updates
for a dataset.
Points to a
ChangeNotification (inherited from TCustomMSDataSet) TMSChangeNotification
component.
Used to specify the wait time
before terminating theCommandTimeout (inherited from TCustomMSDataSet) attempt to execute acommand and generating anerror.
Used to add WHERE
Conditions (inherited from TCustomDADataSet)
conditions to a query
Used to specify aconnection object that will beConnection (inherited from TCustomMSDataSet)
used to connect to a datastore.
Cursor types supported by
CursorType (inherited from TCustomMSDataSet)
SQL Server.
Used to set data type
DataTypeMap (inherited from TCustomDADataSet)
mapping rules
Used to display executing
statement, all its parameters'
Debug (inherited from TCustomDADataSet)
values, and the type ofparameters.
Used to specify the fields
that correspond to the
DetailFields (inherited from TCustomDADataSet)
foreign key fields fromMasterFields when building
master/detail relationship.
Used to keep dataset
Disconnected (inherited from TCustomDADataSet)
opened after connection isclosed.
© 2019 Devart

850

SQL Server Data Access Components

Encryption (inherited from TCustomMSDataSet)

FetchRows (inherited from TCustomDADataSet)

FilterSQL (inherited from TCustomDADataSet)

FinalSQL (inherited from TCustomDADataSet)

IndexFieldNames (inherited from TMemDataSet)
IsQuery (inherited from TCustomDADataSet)
KeyExclusive (inherited from TMemDataSet)

KeyFields (inherited from TCustomDADataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

MacroCount (inherited from TCustomDADataSet)
Macros (inherited from TCustomDADataSet)
MasterFields (inherited from TCustomDADataSet)

Used to specify encryption
options in a dataset.
Used to define the numberof rows to be transferred
across the network at thesame time.
Used to change the WHERE
clause of SELECT
statement and reopen aquery.
Used to return SQL text withall changes performed by
AddWhere, SetOrderBy,
and FilterSQL, and withexpanded macros.
Used to get or set the list offields on which the recordset
is sorted.
Used to check whether SQL
statement returns rows.
Specifies the upper andlower boundaries for arange.
Used to build SQL
statements for the
SQLDelete, SQLInsert, andSQLUpdate properties ifthey were empty before
updating the database.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Used to get the number ofmacros associated with the
Macros property.
Makes it possible to change
SQL queries easily.
Used to specify the namesof one or more fields that are© 2019 DevartReference

MasterSource (inherited from TCustomDADataSet)

Options (inherited from TCustomMSDataSet)

ParamCheck (inherited from TCustomDADataSet)

ParamCount (inherited from TCustomDADataSet)
Params (inherited from TCustomMSDataSet)
Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)
ReadOnly (inherited from TCustomDADataSet)
RefreshOptions (inherited from TCustomDADataSet)

RowsAffected (inherited from TCustomDADataSet)

SmartFetch (inherited from TCustomMSDataSet)

SQL (inherited from TCustomDADataSet)© 2019 Devart

851

used as foreign keys fordataset when establishingdetail/master relationshipbetween it and the dataset
specified in MasterSource.
Used to specify the data
source component whichbinds current dataset to themaster one.
Used to specify the
behaviour of a
TCustomMSDataSet object.
Used to specify whether
parameters for the Params
property are generated
automatically after the SQL
property was changed.
Used to indicate how many
parameters are there in the
Params property.
Contains parameters for aquery's SQL statement.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to prevent users fromupdating, inserting, ordeleting data in the dataset.
Used to indicate when theediting record is refreshed.
Used to indicate the numberof rows which were inserted,
updated, or deleted during
the last query operation.
The SmartFetch mode isused for fast navigation
through a huge amount ofrecords and to minimize
memory consumption.
Used to provide a SQL
statement that a querycomponent executes when

852

SQL Server Data Access Components

SQLDelete (inherited from TCustomDADataSet)

SQLInsert (inherited from TCustomDADataSet)

SQLLock (inherited from TCustomDADataSet)

SQLRecCount (inherited from TCustomDADataSet)

SQLRefresh (inherited from TCustomDADataSet)

SQLUpdate (inherited from TCustomDADataSet)

UniDirectional (inherited from TCustomDADataSet)

UpdateObject (inherited from TCustomMSDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

its Open method is called.
Used to specify a SQL
statement that will be used
when applying a deletion toa record.
Used to specify the SQL
statement that will be used
when applying an insertion
to a dataset.
Used to specify a SQL
statement that will be used
to perform a record lock.
Used to specify the SQL
statement that is used to get
the record count when
opening a dataset.
Used to specify a SQL
statement that will be used
to refresh current record bycalling theTCustomDADataSet.Refres
hRecord procedure.
Used to specify a SQL
statement that will be used
when applying an update toa dataset.
Used if an application does
not need bidirectional
access to records in the
result set.
Used to point to an update
object component which
provides SQL statementsthat perform updates ofread-only datasets.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Published© 2019 DevartReference

Name

853

Description
Defines whether to request
all records of the query fromdatabase server when thedataset is being opened.
Used to specify what kind oflock will be performed when
editing a record.
Used to build ORDER BY
clause of SQL statements.
Used to specify the name ofthe database table thiscomponent encapsulates.

FetchAll

LockMode
OrderFields
TableName

See Also
TMSTable Class
TMSTable Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19.2.1 FetchAll Property

Defines whether to request all records of the query from database server when the dataset isbeing opened.

Class
TMSTable

Syntaxproperty FetchAll: boolean;

Remarks
When set to True, all records of the query are requested from database server when thedataset is being opened. When set to False, records are retrieved when a data-aware
component or a program requests it. If a query can return a lot of records, set this property to
False if initial response time is important.
When the FetchAll property is False, the first call to TMemDataSet.Locate and
TMemDataSet.LocateEx methods may take a lot of time to retrieve additional records to theclient side.

© 2019 Devart

854

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19.2.2 LockMode Property

Used to specify what kind of lock will be performed when editing a record.

Class
TMSTable

Syntaxproperty LockMode: TLockMode;

Remarks
Use the LockMode property to define what kind of lock will be performed when editing arecord. Locking a record is useful in creating multi-user applications. It prevents modificationof a record by several users at the same time.
Locking is performed by the RefreshRecord method.
The default value is lmNone.

See Also
TMSStoredProc.LockMode
TMSQuery.LockMode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19.2.3 OrderFields Property

Used to build ORDER BY clause of SQL statements.

Class
TMSTable

Syntaxproperty OrderFields: string;

Remarks
TMSTable uses the OrderFields property to build ORDER BY clause of SQL statements. To© 2019 DevartReference855

set several field names to this property separate them with commas.
TMSTable is reopened when OrderFields is being changed.

See Also
TMSTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.19.2.4 TableName Property

Used to specify the name of the database table this component encapsulates.

Class
TMSTable

Syntaxproperty TableName: string;

Remarks
Use the TableName property to specify the name of the database table this component
encapsulates. If TCustomDADataSet.Connection is assigned at design time,select a valid
table name from the TableName drop-down list in Object Inspector.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.20 TMSTableData Class

A component for working with user-defined table types in SQL Server 2008.
For a list of all members of this type, see TMSTableData members.

Unit
MSAccess

SyntaxTMSTableData = class(TMemDataSet);

Remarks
The TMSTableData allows working with table types in SQL Server 2008. Use the© 2019 Devart

856

SQL Server Data Access Components

TMSTableData.TableTypeName property to specify the table type.
When adding, changing, and deleting operations in dataset, data are stored in an internalcache on the client side. Data are sent to the server only as data of Table-Valued Parameterswhen a stored procedure is executed. To assign dataset contents to a parameter use theTable property.

Inheritance Hierarchy
TMemDataSet
TMSTableData

See Also
Using Table-Valued Parameters© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.20.1 Members

TMSTableData class overview.

Properties
Name
CachedUpdates (inherited from TMemDataSet)

Connection
IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

Description
Used to enable or disable
the use of cached updates
for a dataset.
Specifies a connection
object that will be used toconnect to a data store.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
© 2019 DevartReference

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

Table

TableTypeName

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

857

Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used for assigning datafrom TMSTableData to a
stored procedureparameter.
Specifies the name of userdefine table type to workwith.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)© 2019 Devart

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.

858

SQL Server Data Access Components

GetBlob (inherited from TMemDataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on the© 2019 DevartReference

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

859

server and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.13.1.20.2 Properties

Properties of the TMSTableData class.
For a complete list of the TMSTableData class members, see the TMSTableData Members
topic.

PublicName
CachedUpdates (inherited from TMemDataSet)

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)© 2019 Devart

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.

860

SQL Server Data Access Components

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

Table

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used for assigning datafrom TMSTableData to a
stored procedureparameter.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Published
Name

Description
Specifies a connection
object that will be used toconnect to a data store.
Specifies the name of userdefine table type to workwith.

Connection

TableTypeName

See Also
TMSTableData Class
TMSTableData Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference861

5.13.1.20.2.1 Connection Property

Specifies a connection object that will be used to connect to a data store.

Class
TMSTableData

Syntaxproperty Connection: TCustomMSConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TCustomMSConnection or its
descendant class objects.
At runtime, set the Connection property to reference an existing TCustomMSConnection
object.

See Also
TCustomMSConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.20.2.2 Table Property

Used for assigning data from TMSTableData to a stored procedure parameter.

Class
TMSTableData

Syntaxproperty Table: TMSSQLTableObject;

Remarks
Use the Table property to assign data from TMSTableData to a stored procedure parameter.

ExampleMSStoredProc.ParamByName('TVP').AsTable := MSTableData.Table;© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

862

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.13.1.20.2.3 TableTypeName Property

Specifies the name of user-define table type to work with.

Class
TMSTableData

Syntaxproperty TableTypeName: string;

Remarks
Use the TableTypeName property to specify the name of user-define table type to work with.
If Connection is assigned at design time, you can select a valid table type name from theTableTypeName drop-down list in Object Inspector.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21 TMSUDTField ClassA field class providing native access to the CLR User-defined Types (UDT) fields of SQL
Server.
For a list of all members of this type, see TMSUDTField members.

Unit
MSAccess

SyntaxTMSUDTField = class(TBlobField);

Remarks
This field class is designed to provide native access to the CLR User-defined Types (UDT)
fields of SQL Server. UDT fields are mapped to TMSUDTField only if SQL Native Client isused as TMSConnection.Options. Otherwise, UDT fields are mapped to TVarBytesField.
You can get information about the underlying UDT using TMSUDTField.AssemblyTypename,
TMSUDTField.UDTCatalogname, TMSUDTField.UDTName,
TMSUDTField.UDTSchemaname. Extended abilities of UDT fields are accessible in Win32© 2019 DevartReference863

applications through the TMSUDTField.AsUDT property.
Note: The CLR integration is disabled by default, so you should enable it to work with UDT.
http://msdn2.microsoft.com/library/ms254506(VS.80).aspx of MSDN describes how to enable
CLR support for SQL Server.

See Also
Working with User Defined Types (UDT)TMSUDTField.AsUDT© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.1 Members

TMSUDTField class overview.

Properties
Name

Description
Used to indicate the typename prefixed bynamespace.
Used to access properties
and methods of CLR Userdefined Types (UDT) fromthe Win32 applications.
Used to indicate the name of
the catalog where UDT is
defined.
Used to indicate the name of
the assembly containing the
UDT class.
Used to indicate the name ofthe schema where UDT is
defined.

AssemblyTypename

AsUDT

UDTCatalogname

UDTName

UDTSchemaname© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.2 Properties

Properties of the TMSUDTField class.
For a complete list of the TMSUDTField class members, see the TMSUDTField Members
topic.
© 2019 Devart

864

SQL Server Data Access Components

PublicName

Description
Used to indicate the typename prefixed bynamespace.
Used to access properties
and methods of CLR Userdefined Types (UDT) fromthe Win32 applications.
Used to indicate the name of
the catalog where UDT is
defined.
Used to indicate the name of
the assembly containing the
UDT class.
Used to indicate the name ofthe schema where UDT is
defined.

AssemblyTypename

AsUDT

UDTCatalogname

UDTName

UDTSchemaname

See Also
TMSUDTField Class
TMSUDTField Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.2.1 AssemblyTypename Property

Used to indicate the type name prefixed by namespace.

Class
TMSUDTField

Syntaxproperty AssemblyTypename: string;

Remarks
Indicates the type name prefixed by namespace if applicable.
This property is read-only.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

865

Devart. All Rights
Reserved.
5.13.1.21.2.2 AsUDT Property

Used to access properties and methods of CLR User-defined Types (UDT) from the Win32
applications.

Class
TMSUDTField

Syntaxproperty AsUDT: Variant;Remarks
The AsUDT property lets you access properties and methods of CLR User-defined Types(UDT) from your Win32 applications. In order to use this functionality, you should create a
CLR assembly that implements your new UDT, register this assembly in SQL Server, andcreate a table containing a column based on your UDT. Also it is necessary to put the CLR
assembly implementing your UDT into the directory with your application using SDAC, orregister it in GAC.
After that you can open tables with UDT fields, cast these fields to TMSUDTField, and invoke
members of your UDT through the AsUDT property.
For detailed information on what is UDT, how to create and use it, please refer to this topic of
MSDN.
Note: if you use this functionality in your application, you will need to deploy theDevart.Sdac.UDTProxy.dll file along with it. This file should be present in the directory withyour application, or registered in GAC. You will find this file in the Bin folder of your SDAC
installation directory.
Note: This functionality has certain restrictions, like:.NET framework 2 or higher should be installed on the client computer;can be used only in Win32 applications;
restrictions of User-defined Types itself, see here for more details.

ExampleYou can open tables with UDT fields, cast these fields to TMSUDTField, and invoke membersof your UDT through the AsUDT property like it is shown in the code below.
This code is taken from the UDT demo of the SDAC General demo. Please refer to this demo
for an example. Also the UDT demo includes an implementation of the test UDT named© 2019 Devart

866

SQL Server Data Access Components

Square.
var
Square: variant;
begin
MSQuery.Edit;
Square := (MSQuery.FieldByName('c_square') as TMSUDTField).AsUDT;
Square.Move(StrToInt(edBaseX.Text), StrToInt(edBaseY.Text));
MSQuery.Post;end;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.2.3 UDTCatalogname Property

Used to indicate the name of the catalog where UDT is defined.

Class
TMSUDTField

Syntaxproperty UDTCatalogname: string;

Remarks
Indicates the name of the catalog where UDT is defined.
This property is read-only.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.2.4 UDTName Property

Used to indicate the name of the assembly containing the UDT class.

Class
TMSUDTField

Syntaxproperty UDTName: string;

Remarks
Indicates the name of the assembly containing the UDT class.

© 2019 DevartReference

867

This property is read-only.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.21.2.5 UDTSchemaname Property

Used to indicate the name of the schema where UDT is defined.

Class
TMSUDTField

Syntaxproperty UDTSchemaname: string;

Remarks
Indicates the name of the schema where UDT is defined.
This property is read-only.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.22 TMSUpdateSQL Class

A component for tuning update operations for the DataSet component.
For a list of all members of this type, see TMSUpdateSQL members.

Unit
MSAccess

SyntaxTMSUpdateSQL = class(TCustomDAUpdateSQL);

Remarks
Use the TMSUpdateSQL component to provide DML statements for the dataset componentsthat return read-only result set. This component also allows setting objects that can be used
for executing update operations. You may prefer to use directly SQLInsert, SQLUpdate, andSQLDelete properties of the TCustomDADataSet descendants.

Inheritance Hierarchy© 2019 Devart

868

SQL Server Data Access Components

TCustomDAUpdateSQLTMSUpdateSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.22.1 Members

TMSUpdateSQL class overview.

Properties
Name

Description
Used to hold a reference to
DataSet (inherited from TCustomDAUpdateSQL)
the TCustomDADataSet
object that is being updated.
Provides ability to perform
DeleteObject (inherited from TCustomDAUpdateSQL) advanced adjustment of thedelete operations.
Used when deleting a
DeleteSQL (inherited from TCustomDAUpdateSQL)
record.
Provides ability to perform
InsertObject (inherited from TCustomDAUpdateSQL)
advanced adjustment ofinsert operations.
Used when inserting a
InsertSQL (inherited from TCustomDAUpdateSQL)
record.
Provides ability to perform
LockObject (inherited from TCustomDAUpdateSQL)
advanced adjustment of lock
operations.
Used to lock the current
LockSQL (inherited from TCustomDAUpdateSQL)
record.
Provides ability to perform
ModifyObject (inherited from TCustomDAUpdateSQL) advanced adjustment ofmodify operations.
Used when updating a
ModifySQL (inherited from TCustomDAUpdateSQL)
record.
Provides ability to perform
RefreshObject (inherited from TCustomDAUpdateSQL) advanced adjustment of
refresh operations.
Used to specify an SQL
statement that will be used
RefreshSQL (inherited from TCustomDAUpdateSQL) for refreshing the current
record byTCustomDADataSet.Refres
hRecord procedure.
© 2019 DevartReference

SQL (inherited from TCustomDAUpdateSQL)

869

Used to return a SQL
statement for one of the
ModifySQL, InsertSQL, orDeleteSQL properties.

Methods
Name
Apply (inherited from TCustomDAUpdateSQL)

Description
Sets parameters for a SQL
statement and executes it to
update a record.

ExecSQL (inherited from TCustomDAUpdateSQL)

Executes a SQL statement.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.23 TMSXMLField ClassA class providing access to the SQL Server xml data type.
For a list of all members of this type, see TMSXMLField members.

Unit
MSAccess

SyntaxTMSXMLField = class(TWideMemoField);

Remarks
TMSXMLField provides access to the SQL Server xml data type.
The TMSXMLField.DataType property values equal to ftXML. You can access actual XML
document using the AsString and TMSXMLField.XML properties.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.13.1.23.1 Members

TMSXMLField class overview.

Properties© 2019 Devart

DAC Forum

Provide Feedback

870

SQL Server Data Access Components

Name

Description
Contains information about
typed XML column.
Indicates if an XML column
is typed.
Returns an XML document
or a fragment of XML
document as string.

SchemaCollection
Typed
XML
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.23.2 Properties

Properties of the TMSXMLField class.
For a complete list of the TMSXMLField class members, see the TMSXMLField Members
topic.

PublicName

Description
Contains information about
typed XML column.
Indicates if an XML column
is typed.
Returns an XML document
or a fragment of XML
document as string.

SchemaCollection
Typed
XML

See Also
TMSXMLField ClassTMSXMLField Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.23.2.1 SchemaCollection Property

Contains information about typed XML column.

Class
TMSXMLField© 2019 DevartReference

871

Syntaxproperty SchemaCollection: TMSSchemaCollection;

Remarks
Contains the following XML schema information about a typed XML column.

Name
CatalogName
SchemaName

The name of a catalog in which an XML schema collection is defined.
Empty for an untyped XML column.
The name of a schema in which an XML schema collection is defined.
Empty for an untyped XML column.
The name of XML schema collection. Empty for an untyped XML
column.

See Also
Typed© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.1.23.2.2 Typed Property

Indicates if an XML column is typed.

Class
TMSXMLField

Syntaxproperty Typed: boolean;

Remarks
Indicates whether an XML column is typed. If XML column is typed, the SchemaCollection
property is filled.

See Also
SchemaCollection© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

872

SQL Server Data Access Components

5.13.1.23.2.3 XML Property

Returns an XML document or a fragment of XML document as string.

Class
TMSXMLField

Syntaxproperty XML: string;

Remarks
Returns an XML document or a fragment of XML document as string.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.2 Types
Types in the MSAccess unit.

Types
Name

Description
This type is used for the
TMSChangeNotification.On
Change event.
This type is used for the
TCustomMSDataSet.AfterU
pdateExecute andTCustomMSDataSet.Before
UpdateExecute events.

TMSChangeNotificationEvent

TMSUpdateExecuteEvent© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.2.1 TMSChangeNotificationEvent Procedure ReferenceThis type is used for the TMSChangeNotification.OnChange event.

Unit
MSAccess

Syntax© 2019 DevartReference

873

TMSChangeNotificationEvent = procedure (Sender: TObject; DataSet:
TCustomMSDataSet; NotificationInfo: TMSNotificationInfo;
NotificationSource: TMSNotificationSource; NotificationType:TMSNotificationType) of object;Parameters
SenderAn object that raised the event.
DataSetNotificationInfo
NotificationSource
NotificationType© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.2.2 TMSUpdateExecuteEvent Procedure ReferenceThis type is used for the TCustomMSDataSet.AfterUpdateExecute andTCustomMSDataSet.BeforeUpdateExecute events.

Unit
MSAccess

SyntaxTMSUpdateExecuteEvent = procedure (Sender: TCustomMSDataSet;
StatementTypes: TStatementTypes; Params: TMSParams) of object;Parameters
SenderAn object that raised the event.
StatementTypes
Holds the type of the SQL statement being executed.
ParamsHolds the parameters with which the SQL statement will be executed.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

874

SQL Server Data Access Components

5.13.3 Enumerations
Enumerations in the MSAccess unit.

Enumerations
Name

Description
Specifies the extent to which
all outside transactions
interfere with the subsequenttransactions of the current
connection.
Specifies the parameters forlocking the current record.
Indicates the reason of thenotification.
Indicates the source of
notification.
Indicates if this notification is
generated because ofchange or by subscription.
Enumerates the object types
supported by TMSMetadata.

TIsolationLevelTMSLockType
TMSNotificationInfo
TMSNotificationSource
TMSNotificationType
TMSObjectType© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.3.1 TIsolationLevel Enumeration

Specifies the extent to which all outside transactions interfere with the subsequenttransactions of the current connection.

Unit
MSAccess

SyntaxTIsolationLevel = (ilReadCommitted, ilReadUnCommitted,
ilRepeatableRead, ilIsolated, ilSnapshot);

ValuesValue

Meaning

ilIsolated

The most restricted level of transaction isolation. Database© 2019 DevartReference

875

server isolates data involved in current transaction by putting
additional processing on range locks. Used to put aside allundesired effects observed in the concurrent accesses to thesame set of data, but may lead to a greater latency at times of acongested database environment.
Sets isolation level at which transaction cannot see changes
ilReadCommitted made by outside transactions until they are committed. Only dirty
reads (changes made by uncommitted transactions) areeliminated by this state of the isolation level. The default value.
The most unrestricted level of the transaction isolation. All types
ilReadUnCommitte of data access interferences are possible. Mainly used fordbrowsing database and to receive instant data with prospective
changes.
Prevents concurrent transactions from modifying data in thecurrent uncommitted transaction. This level eliminates dirty reads
ilRepeatableRead as well as nonrepeatable reads (repeatable reads of the samedata in one transaction before and after outside transactions may
have started and committed).
Uses row versioning. Provides transaction-level readconsistency. A data snapshot is taken when the snapshot
ilSnapshot
transaction starts, and remains consistent for the duration of atransaction.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
5.13.3.2 TMSLockType Enumeration

Specifies the parameters for locking the current record.

Unit
MSAccess

SyntaxTMSLockType = (ltUpdate, ltExclusive);

ValuesValue
ltExclusive
ltUpdate© 2019 Devart

Meaning
The locked record can be neither read nor updated until the lockis released.
The locked record can be read by others, but it cannot be
updated until the lock is released.

876

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.3.3 TMSNotificationInfo Enumeration

Indicates the reason of the notification.

Unit
MSAccess

SyntaxTMSNotificationInfo = (niAlter, niDelete, niDrop, niError,
niInsert, niInvalid, niIsolation, niOptions, niPreviousFire,
niQuery, niResource, niRestart, niTemplateLimit, niTruncate,niUnknown, niUpdate);

ValuesValue
niAlterniDelete
niDropniErrorniInsert
niInvalidniIsolation
niOptionsniPreviousFire
niQueryniResource
niRestartniTemplateLimit
niTruncate

Meaning
One or more underlying server objects were modified.
Data in one or more tables referenced in the underlying query
was deleted by a DELETE statement.
One or more underlying objects were dropped.
An internal error occurred in SQL Server.
Data in one or more tables referenced in the underlying query
was changed by an INSERT statement.
A provided statement does not support notifications (INSERT,UPDATE, etc. statement). See this MSDN topic for the detailed
information about supported statements.
The isolation mode is not valid for query notifications (forexample, Snapshot).
The connection options were not provided correctly.
A previous statement has caused query notifications to fire under
the current transaction.
A SELECT statement that does not correspond to restrictions
was provided.
The notification subscription was removed as there may be notenough server resources.
SQL Server was restarted.
One or more tables used in a query reached the maximum
number of allowed templates.
One or more tables used in the underlying query were truncated.
© 2019 DevartReference

niUnknown
niUpdate© 1997-2019
Devart. All Rights
Reserved.

877

An option sent by the server was not recognized.
Data in one or more underlying tables was changed by an
UPDATE statement.
Request Support

DAC Forum

Provide Feedback

5.13.3.4 TMSNotificationSource Enumeration

Indicates the source of notification.

Unit
MSAccess

SyntaxTMSNotificationSource = (nsClient, nsData, nsDatabase,nsEnvironment, nsExecution, nsObject, nsStatement, nsSystem,
nsTimeout, nsUnknown);

ValuesValue
nsClient
nsDatansDatabasensEnvironment
nsExecution
nsObject
nsStatement
nsSystem
nsTimeout
nsUnknown© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Meaning
Client is the reason of the notification.
Data in one or more tables referenced in the underlying query
was changed.
Database state was changed.
Environment changes that are incompatible with Change
notification were applied.
An error occurred during execution.
One of the underlying objects was changed (altered, dropped,etc.).
The provided query does not support notifications.
A system-related event has occurred (like server restart).
The subscription timeout has been expired.
Used when an option is not recognized.
Request Support

DAC Forum

Provide Feedback

878

SQL Server Data Access Components

5.13.3.5 TMSNotificationType Enumeration

Indicates if this notification is generated because of change or by subscription.

Unit
MSAccess

SyntaxTMSNotificationType = (ntChange, ntSubscribe, ntUnknown);

ValuesValue
ntChange
ntSubscribe
ntUnknown© 1997-2019
Devart. All Rights
Reserved.

Meaning
Data on the server was actually changed.
Notification subscription failed when creating.
Used when an option is not recognized.
Request Support

DAC Forum

Provide Feedback

5.13.3.6 TMSObjectType Enumeration

Enumerates the object types supported by TMSMetadata.

Unit
MSAccess

SyntaxTMSObjectType = (otDatabases, otTables, otTableConstraints,
otColumns, otIndexes, otStoredProcs, otStoredProcParams,
otColumnPrivileges, otForeignKeys, otPrimaryKeys, otLinkedServers,
otServerTypes, otSchemata, otStatistics, otAliases, otSynonyms,
otViews, otSystemTables, otGlobalTempTables, otLocalTempTables,
otSystemViews, otAliasesInfo, otTablesInfo, otSynonymsInfo,
otSystemTablesInfo, otViewsInfo, otGlobalTempTablesInfo,
otLocalTempTablesInfo, otExternalTablesInfo, otSystemViewsInfo,
otTablePrivileges, otAssemblies, otAssemblyDependencies,
otUserTypes, otXMLCollections, otCheckConstraints,
otCheckConstraintsByTable, otTableStatistics);

Values© 2019 DevartReference

Value

879

Meaning
Restrictions: DatabaseName, SchemaName, TableName
otAliases
Rowset name: TABLES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otAliasesInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, AssemblyName,
otAssemblies
AssemblyID Rowset name: DBSCHEMA_SQL_ASSEMBLIES
RowsetotAssemblyDepen Restrictions: DatabaseName, SchemaName, AssemblyID,
ReferencedAssemblyID Rowset name:dencies
DBSCHEMA_SQL_ASSEMBLY_DEPENDENCIES Rowset
otCheckConstraint Restrictions: DatabaseName, SchemaName, ConstraintNames
Rowset name: CHECK_CONSTRAINTS Rowset
otCheckConstraint Restrictions: DatabaseName, SchemaName, TableName,
ConstraintName Rowset name:sByTable
CHECK_CONSTRAINTS_BY_TABLE Rowset
otColumnPrivilege Restrictions: DatabaseName, SchemaName, TableName,s
ColumnName Rowset name: COLUMN_PRIVILEGES Rowset
Restrictions: DatabaseName, SchemaName, TableName,
otColumns
ColumnName Rowset name: COLUMNS Rowset
Restrictions: DatabaseName Rowset name: CATALOGS
otDatabases
RowsetotExternalTablesInf Restrictions: DatabaseName, SchemaName, TableNameo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName
otForeignKeys
Rowset name: FOREIGN_KEYS Rowset
otGlobalTempTabl Restrictions: DatabaseName, SchemaName, TableName
es
Rowset name: TABLES Rowset
otGlobalTempTabl Restrictions: DatabaseName, SchemaName, TableName
esInfoRowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName
otIndexes
Rowset name: INDEXES Rowset
Restrictions: LinkedServer Rowset name:otLinkedServers
DBSCHEMA_LINKEDSERVERS Rowset
otLocalTempTable Restrictions: DatabaseName, SchemaName, TableNames
Rowset name: TABLES Rowset
otLocalTempTable Restrictions: DatabaseName, SchemaName, TableName
sInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName
otPrimaryKeys
Rowset name: PRIMARY_KEYS Rowset
Restrictions: DatabaseName, SchemaName Rowset name:otSchemata
SCHEMATA Rowset© 2019 Devart

880

SQL Server Data Access Components

otServerTypes

Restrictions: Rowset name: PROVIDER_TYPES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otStatistics
Rowset name: STATISTICS Rowset
otStoredProcPara Restrictions: DatabaseName, SchemaName, TableNamems
Rowset name: STATISTICS Rowset
Restrictions: DatabaseName, SchemaName,otStoredProcs
StoredProcName Rowset name: PROCEDURES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otSynonyms
Rowset name: TABLES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otSynonymsInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName
otSystemTables
Rowset name: TABLES Rowset
otSystemTablesInf Restrictions: DatabaseName, SchemaName, TableNameo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName
otSystemViews
Rowset name: TABLES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otSystemViewsInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName,otTableConstraints ConstraintName Rowset name: TABLE_CONSTRAINTS
RowsetRestrictions: DatabaseName, SchemaName, TableName
otTablePrivileges
Rowset name: TABLE_PRIVILEGES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otTablesRowset name: TABLES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otTablesInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName, TableName,otTableStatistics
StatisticsName Rowset name: TABLE_STATISTICS Rowset
Restrictions: DatabaseName, SchemaName, UDTName
otUserTypes
Rowset name: DBSCHEMA_SQL_USER_TYPES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otViews
Rowset name: TABLES Rowset
Restrictions: DatabaseName, SchemaName, TableName
otViewsInfo
Rowset name: TABLES_INFO Rowset
Restrictions: DatabaseName, SchemaName,otXMLCollections SchemaCollectionName, TargetNamespaceURI Rowset name:DBSCHEMA_XML_COLLECTIONS Rowset

Remarks© 2019 DevartReference

881

Every member of this enumeration specifies restrictions and has representation in the MSDNOLE DB schema rowset name.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.4 Variables
Variables in the MSAccess unit.

Variables
Name

Description
In SDAC 4.00.0.4 updatestatements execution was
optimized. This optimization
changed the behaviour ofaffected rows count retrieval
for the tables with triggers.

__UseUpdateOptimization© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.4.1 __UseUpdateOptimization Variable

In SDAC 4.00.0.4 update statements execution was optimized. This optimization changed the
behaviour of affected rows count retrieval for the tables with triggers.

Unit
MSAccess

Syntax__UseUpdateOptimization: boolean;

Remarks
In SDAC 4.00.0.4 update statements execution was optimized. This optimization changed the
behaviour of affected rows count retrieval for the tables with triggers. If a trigger performs
modifications of other records reacting on a modification in the underlying table, SQL Server
sends several values of affected rows count (including for modifications made by a trigger).
Prior to SDAC 4.00.0.4 the first value was considered as affected rows count, when in SDAC
4.00.0.4 and higher it's the last value. However neither of these two approaches can beconsidered correct, as there can be triggers that snap into action both before modification and© 2019 Devart

882

SQL Server Data Access Components

after modification. There is no way to determine which of the values returned by SQL Serveris the correct value of affected rows count. Therefore we do not recommend using the
RowsAffected property when updating tables with triggers.
The StrictUpdate mode is based on RowsAffected, therefore we also do not recommend
using StrictUpdate when updating tables with triggers.
If you want to disable this optimization, set the __UseUpdateOptimization variable to False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.5 Constants
Constants in the MSAccess unit.

Constants
Name

Description
Read this constant to get thecurrent version number for
SDAC.

SDACVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.13.5.1 SDACVersion Constant

Read this constant to get the current version number for SDAC.

Unit
MSAccess

SyntaxSDACVersion = '9.1.2';© 1997-2019
Devart. All Rights
Reserved.

5.14

Request Support

DAC Forum

Provide Feedback

MSClasses
This unit contains implementation of SQL Server classes.

Enumerations© 2019 DevartReference

Name

Description
Specifies the application
workload type whenconnecting to a server.
Specifies the way of buffer
pool flushing on transaction
commit.
Used in
TMSCompactEdition todefine the version of SQL
Server Compact Edition.
Specifies the authentication
service used by databaseserver to identify a user.
Cursor types supported by
SQL Server.
Specifies file modes for
opening a database file.
Determines which system
function to use to obtain an
identifier when adding arecord.
Use this property to specify
a provider from the list of
supported providers.
Used in TMSConnection todefine the version of SQL
Native Client.

TApplicationIntent

TCompactCommitMode

TCompactVersion

TMSAuthentication
TMSCursorType
TMSInitMode

TMSLastIdentityValueFunction

TMSProvider

TNativeClientVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

883

DAC Forum

Provide Feedback

5.14.1 Enumerations
Enumerations in the MSClasses unit.

Enumerations
Name
TApplicationIntent

Description
Specifies the application
workload type whenconnecting to a server.

TCompactCommitMode

Specifies the way of buffer
pool flushing on transaction© 2019 Devart

884

SQL Server Data Access Components

commit.
Used in
TMSCompactEdition todefine the version of SQL
Server Compact Edition.
Specifies the authentication
service used by databaseserver to identify a user.
Cursor types supported by
SQL Server.
Specifies file modes for
opening a database file.
Determines which system
function to use to obtain an
identifier when adding arecord.
Use this property to specify
a provider from the list of
supported providers.
Used in TMSConnection todefine the version of SQL
Native Client.

TCompactVersion

TMSAuthentication
TMSCursorType
TMSInitMode

TMSLastIdentityValueFunction

TMSProvider

TNativeClientVersion© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.14.1.1 TApplicationIntent Enumeration

Specifies the application workload type when connecting to a server.

Unit
MSClasses

SyntaxTApplicationIntent = (aiReadWrite, aiReadOnly);

ValuesValue
aiReadOnly
aiReadWrite

Meaning
Client requests a read workload.
Client requests a read-write workload.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

885

Devart. All Rights
Reserved.
5.14.1.2 TCompactCommitMode Enumeration

Specifies the way of buffer pool flushing on transaction commit.

Unit
MSClasses

SyntaxTCompactCommitMode = (cmAsynchCommit, cmSynchCommit);

ValuesValue
Meaning
cmAsynchCommit Asynchronous commit to disk. The default value.
cmSynchCommit Synchronous commit to disk.
© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
5.14.1.3 TCompactVersion Enumeration

Used in TMSCompactEdition to define the version of SQL Server Compact Edition.

Unit
MSClasses

SyntaxTCompactVersion = (cvAuto, cv30, cv35);

Values
Value
cv30
cv35
cvAuto© 1997-2019© 2019 Devart

Meaning
Use SQL Server Compact Edition version 3.0 or 3.1.
Use SQL Server Compact Edition version 3.5.
Tries to define the server version using the version of databasefile. If it is impossible, tries to work as with cv35 value assigned, if
this is also impossible - as with cv30.
Request Support

DAC Forum

Provide Feedback

886

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.14.1.4 TMSAuthentication Enumeration

Specifies the authentication service used by database server to identify a user.

Unit
MSClasses

SyntaxTMSAuthentication = (auWindows, auServer);ValuesValue

auServerauWindows© 1997-2019
Devart. All Rights
Reserved.

Meaning
An alternative way of identifying users by database server. To
establish a connection valid TCustomDAConnection.Username
and TCustomDAConnection.Password either hardcoded into
application or provided in the server login prompt fields are
required. The default value.
Uses Windows NT/2000/XP integrated security, or"SSPI" (Security Support Provider Interface). The Username,
Password, and LoginPrompt properties are ignored.
Request Support

DAC Forum

Provide Feedback

5.14.1.5 TMSCursorType Enumeration

Cursor types supported by SQL Server.

Unit
MSClasses

SyntaxTMSCursorType = (ctDefaultResultSet, ctStatic, ctKeyset, ctDynamic,
ctBaseTable);

ValuesValue

Meaning© 2019 DevartReference

887

Base table cursor. This cursor is used for working with Compact
Edition. This cursor is the fastest of the SQL server cursors andthe only cursor that interacts directly with the storage engine. This
allows to increase the speed of data access several times. Data
modifications, deletions, and insertions by other users are visible.
ctBaseTable
If UniDirectional=False, the cursor is used only when fetching
data, and Data updates are reflected on database by SQL
statements execution. In order to use the cursor also for data
modification it is necessary to set the UniDirectional property toTrue. But in this case the cursor does not support bookmarks andcannot be represented in multiline controls such as DBGrid.
By the old SQL Server terminology is the Firehose cursor. It
ctDefaultResultSet serves for the fastest data fetch from server to the client side.
Allows to run batches. Data updates are reflected in the database
only by SQL statements execution. The default value.
Dynamic cursor. Used when data is not cached at the server andfetch is performed row by row as required. Doesn't support
bookmarks and cannot be represented in multiline controls such
ctDynamic
as DBGrid. Data modifications, deletions, and insertions by otherusers are visible. Data updates are reflected on database bothby SQL statements execution and server cursors means.
Allows to cache only keyfields at the server. Fetching is
performed row by row when a data-aware component or aprogram requests it. Records added by other users are not
ctKeyset
visible, and records deleted by other users are inaccessible.
Data updates are reflected in the database both by SQL
statements execution and server cursors means.
Static copying of records. Query execution results are cashed at
the server. Fetch is performed row by row when a data-aware
ctStatic
component or a program requests it. When a cursor is opened,
all newly added updates are invisible. Used mostly for reporting.

Remarks
ctStatic, ctKeyset, and ctDynamic cursors are server cursors. So theTCustomDADataSet.FetchRows, TCustomMSDataSet.FetchAll,
TMemDataSet.CachedUpdates properties don't have any influence on such cursors and only
the Options.CursorUpdate option does.
The default value is ctDefaultResultSet.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

888

SQL Server Data Access Components

5.14.1.6 TMSInitMode Enumeration

Specifies file modes for opening a database file.

Unit
MSClasses

SyntaxTMSInitMode = (imReadOnly, imReadWrite, imExclusive, imShareRead);

ValuesValue
imExclusive
imReadOnly
imReadWrite
imShareRead© 1997-2019
Devart. All Rights
Reserved.

Meaning
Database file is opened for exclusive use. This mode prevents
others from opening this database file.
Database file is opened for reading. Any modification operations
are not allowed.
Both read and write operations are allowed. The default value.
The database file is opened for reading and writing only by one
user. Other users can not read or write to the database file.
Request Support

DAC Forum

Provide Feedback

5.14.1.7 TMSLastIdentityValueFunction Enumeration

Determines which system function to use to obtain an identifier when adding a record.

Unit
MSClasses

SyntaxTMSLastIdentityValueFunction = (vfScopeIdentity, vfIdentCurrent,
vfIdentity);

ValuesValue
vfIdentCurrent
vfIdentity

Meaning
The IDENT_CURRENT system function is used. It returns the last
identity value generated for a specified table or view. The last
identity value generated can be for any session and any scope.
The @@IDENTITY system function is used. It returns the last© 2019 DevartReference

vfScopeIdentity© 1997-2019
Devart. All Rights
Reserved.

889

inserted identity value.
The SCOPE_IDENTITY system function is used. It returns the last
identity value inserted into an identity column in the same scope.
A scope is a module: a stored procedure, trigger, function, orbatch.
Request Support

DAC Forum

Provide Feedback

5.14.1.8 TMSProvider Enumeration

Use this property to specify a provider from the list of supported providers.

Unit
MSClasses

SyntaxTMSProvider = (prAuto, prSQL, prNativeClient, prCompact, prDirect,
prMSOLEDB);

ValuesValue

prAutoprCompact
prDirectprMSOLEDB

prNativeClient© 2019 Devart

Meaning
prAuto is the default value of the Provider property. With default
value, SDAC will use one of the supported providers in thefollowing order:
1. prNativeClient
2. prMSOLEDB
3. prSQLFirst SDAC checks whether SQL Server Native Client is installed
on your system. If SQL Server Native Client is not found, SDAC
looks for Microsoft OLE DB Driver for SQL Server. If neither
SQLNCLI nor MSOLEDBSQL is installedon your system, thedriver will use Microsoft OLE DB Provider for SQL Server.
SQL Server Compact Edition provider.
Connect to SQL Server directly via TCP/IP.
Uses Microsoft OLE DB Driver for SQL Server (MSOLEDBSQL).
You need to have the driver installed on your system to use thisvalue for Provider.
Uses the SQL Native Client. It should be installed on thecomputer to use this Provider value. This provider offers the
maximum functionality set.

890

SQL Server Data Access Components

prSQL

Uses the provider preinstalled with Windows that has limited
functionality.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.14.1.9 TNativeClientVersion Enumeration

Used in TMSConnection to define the version of SQL Native Client.

Unit
MSClasses

SyntaxTNativeClientVersion = (ncAuto, nc2005, nc2008, nc2012);

ValuesValue
nc2005nc2008nc2012
ncAuto© 1997-2019
Devart. All Rights
Reserved.

5.15

Meaning
SQL Native Client 9 is used. SQL Native Client 9 is shipped withSQL Server versions since SQL Server 2005.
SQL Native Client 10 is used. SQL Native Client 10 is shippedwith SQL Server 2008.
SQL Native Client 11 is used. SQL Native Client 11 is shippedwith SQL Server 2012.
SDAC looks for an available SQL Native Client provider in thefollowing sequence: Native Client 11, Native Client 10, Native
Client 9. The first found provider from the sequence is used.
Request Support

DAC Forum

Provide Feedback

MSCompactConnection
This unit contains implementation of the TMSCompactConnection class.

ClassesName

Description

TMSCompactConnection

A component forestablishing connection to
Microsoft SQL Server© 2019 DevartReference

Compact Edition, providing
customized login support,
and performing transaction
control.
This class allows setting up
the behaviour of the
TMSCompactConnection
class.

TMSCompactConnectionOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

891

DAC Forum

Provide Feedback

5.15.1 Classes
Classes in the MSCompactConnection unit.

ClassesName

Description
A component forestablishing connection to
Microsoft SQL Server
Compact Edition, providing
customized login support,
and performing transaction
control.
This class allows setting up
the behaviour of the
TMSCompactConnection
class.

TMSCompactConnection

TMSCompactConnectionOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1 TMSCompactConnection Class

A component for establishing connection to Microsoft SQL Server Compact Edition , providing
customized login support, and performing transaction control.
For a list of all members of this type, see TMSCompactConnection members.

Unit
MSCompactConnection

Syntax© 2019 Devart

892

SQL Server Data Access Components

TMSCompactConnection = class(TCustomMSConnection);

Remarks
The TMSCompactConnection component is used to establish connection to Microsoft SQL
Server Compact Edition , provide customized login support, and perform transaction control.
TMSCompactConnection publishes connection-related properties derived from its ancestor
class TCustomMSConnection.
Note: if you would like to use SDAC in a service, console or just in a separate thread, youneed to call CoInitialize for each thread. Also call CoUnInitialize when the thread is finished.

Inheritance Hierarchy
TCustomDAConnection
TCustomMSConnection
TMSCompactConnection

See Also
TCustomMSDataSet.Connection
TMSSQL.Connection
MSDN: Microsoft SQL Server Compact Edition© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.1 Members

TMSCompactConnection class overview.

Properties
Name

Description
Contains the version of
ClientVersion (inherited from TCustomMSConnection) Microsoft OLE DB Provider
for SQL Server.
Allows to link a
ConnectDialog (inherited from TCustomDAConnection) TCustomConnectDialog
component.
Used to specify theConnectString (inherited from TCustomDAConnection) connection information, suchas: UserName, Password,
Server, etc.
ConvertEOL (inherited from TCustomDAConnection) Allows customizing line
© 2019 DevartReference893

breaks in string fields andparameters.
Used to specify the
database name that is a
Database
default source of data for
SQL queries once a
connection is established.
Used to specify the file
InitMode
mode to be used for
opening a database file.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLevel (inherited from TCustomMSConnection) transactions interfere withsubsequent transactions of
the current connection.
Specifies the number oflocks to perform before
LockEscalation
escalating from row to tableor from page to table..
Used to specify the time for
LockTimeout
which a transaction will wait
for a lock.
Specifies whether a login
LoginPrompt (inherited from TCustomDAConnection) dialog appears immediately
before opening a newconnection.
Used to specify the
behaviour of a
Options
TMSCompactConnection
object.
Serves to supply a
Password (inherited from TCustomDAConnection)
password for login.
Enables or disables using
Pooling (inherited from TCustomDAConnection)connection pool.
PoolingOptions (inherited fromSpecifies the behaviour ofTCustomDAConnection)connection pool.

Serves to supply the server
name for login.
ServerVersion (inherited from TCustomMSConnection) Contains the exact numberof the SQL Server version.
TransactionCommitMode
Used to specify the way theServer (inherited from TCustomDAConnection)© 2019 Devart

894

SQL Server Data Access Components

Username (inherited from TCustomDAConnection)buffer pool will be flushed ontransaction commit.
Used to supply a user namefor login.

Methods
Name

Description
ApplyUpdates (inherited from TCustomDAConnection) Overloaded. Applies
changes in datasets.
Shares database
AssignConnect (inherited fromconnection between the
TCustomMSConnection)
TCustomMSConnection
components.
Commit (inherited from TCustomDAConnection)
Commits current transaction.
Connect (inherited from TCustomDAConnection)

CreateSQL (inherited from TCustomMSConnection)
Disconnect (inherited from TCustomDAConnection)
ExecProc (inherited from TCustomDAConnection)

ExecProcEx (inherited from TCustomDAConnection)
ExecSQL (inherited from TCustomDAConnection)

ExecSQLEx (inherited from TCustomDAConnection)
GetDatabaseNames (inherited fromTCustomDAConnection)
GetKeyFieldNames (inherited fromTCustomDAConnection)
GetStoredProcNames (inherited fromTCustomDAConnection)

Establishes a connection to
the server.
Returns a new instance of
the TMSSQL class andassociates it with thisconnection object.
Performs disconnect.
Allows to execute stored
procedure or function
providing its name andparameters.
Allows to execute a stored
procedure or function.
Executes a SQL statementwith parameters.
Executes any SQL
statement outside the
TQuery or TSQL
components.
Returns a database list fromthe server.
Provides a list of available
key field names.
Returns a list of stored
procedures from the server.

© 2019 DevartReference

GetTableNames (inherited from

895

Provides a list of available
tables names.

TCustomDAConnection)

Sends a specified message
through theTCustomDAConnection)
TCustomDASQLMonitor
component.
OpenDatasets (inherited from TCustomMSConnection) Opens several datasets as
one batch.
Used to check state ofPing (inherited from TCustomDAConnection)connection to the server.
Marks the connection that
RemoveFromPool (inherited fromshould not be returned to theTCustomDAConnection)
pool after disconnect.
Discards all current data
Rollback (inherited from TCustomDAConnection)changes and ends
transaction.
StartTransaction (inherited fromBegins a new user
MonitorMessage (inherited fromTCustomDAConnection)transaction.

EventsName
OnConnectionLost (inherited from

Description
This event occurs whenconnection was lost.

TCustomDAConnection)
OnError (inherited from TCustomDAConnection)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

This event occurs when anerror has arisen in theconnection.
Provide Feedback

5.15.1.1.2 Properties

Properties of the TMSCompactConnection class.
For a complete list of the TMSCompactConnection class members, see the
TMSCompactConnection Members topic.

PublicName© 2019 Devart

Description

896

SQL Server Data Access Components

Contains the version of
ClientVersion (inherited from TCustomMSConnection) Microsoft OLE DB Provider
for SQL Server.
Allows to link a
ConnectDialog (inherited from TCustomDAConnection) TCustomConnectDialog
component.
Used to specify theConnectString (inherited from TCustomDAConnection) connection information, suchas: UserName, Password,
Server, etc.
Allows customizing line
ConvertEOL (inherited from TCustomDAConnection) breaks in string fields andparameters.
InTransaction (inherited from TCustomDAConnection) Indicates whether thetransaction is active.
Used to specify the extent towhich all outside
IsolationLevel (inherited from TCustomMSConnection) transactions interfere withsubsequent transactions of
the current connection.
Specifies whether a login
LoginPrompt (inherited from TCustomDAConnection) dialog appears immediately
before opening a newconnection.
Serves to supply a
Password (inherited from TCustomDAConnection)
password for login.
Enables or disables using
Pooling (inherited from TCustomDAConnection)connection pool.
PoolingOptions (inherited fromSpecifies the behaviour ofTCustomDAConnection)connection pool.

Serves to supply the server
name for login.
ServerVersion (inherited from TCustomMSConnection) Contains the exact numberof the SQL Server version.
Used to supply a user name
Username (inherited from TCustomDAConnection)
for login.
Server (inherited from TCustomDAConnection)

Published
Name
Database

Description
Used to specify the
database name that is a
default source of data for© 2019 DevartReference897

SQL queries once a
connection is established.
Used to specify the filemode to be used for
opening a database file.
Specifies the number oflocks to perform before
escalating from row to tableor from page to table..
Used to specify the time forwhich a transaction will wait
for a lock.
Used to specify the
behaviour of a
TMSCompactConnection
object.
Used to specify the way the
buffer pool will be flushed ontransaction commit.

InitMode

LockEscalation

LockTimeout

Options

TransactionCommitMode

See Also
TMSCompactConnection ClassTMSCompactConnection Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.2.1 Database Property

Used to specify the database name that is a default source of data for SQL queries once a
connection is established.

Class
TMSCompactConnection

Syntaxproperty Database: string;

Remarks
Use the Database property to specify the name of the database to be used once a connection
is open.

© 2019 Devart

898

SQL Server Data Access Components

If the Database property points to an existent database, the database will be opened.
If the Database property points to a non-existent database in a correct system path, further
behavior depends on the value of the TMSCompactConnectionOptions.ForceCreateDatabaseproperty.
If the Database property is set to ":memory:", a new temporary in-memory database will becreated and opened.
If the Database property is empty, a new temporary on-disk database will be created andopened.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.2.2 InitMode Property

Used to specify the file mode to be used for opening a database file.

Class
TMSCompactConnection

Syntaxproperty InitMode: TMSInitMode default DefaultInitMode;

Remarks
Use the InitMode property to specify the file mode that will be used to open the database file.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.2.3 LockEscalation Property

Specifies the number of locks to perform before escalating from row to table or from page totable..

Class
TMSCompactConnection

Syntaxproperty LockEscalation: integer default
DefaultDefaultLockEscalation;

Remarks© 2019 DevartReference

899

Specifies how many locks should be performed before escalating from row to table or frompage to table.
The default value is 100.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.2.4 LockTimeout Property

Used to specify the time for which a transaction will wait for a lock.

Class
TMSCompactConnection

Syntaxproperty LockTimeout: integer default DefaultDefaultLockTimeout;

Remarks
Specifies how much time a transaction will wait for a lock.
Measured in milliseconds.
The default value is 2000.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.1.2.5 Options Property

Used to specify the behaviour of a TMSCompactConnection object.

Class
TMSCompactConnection

Syntaxproperty Options: TMSCompactConnectionOptions;Remarks
Set the properties of Options to specify the behaviour of a TMSCompactConnection object.
Descriptions of all options are in the table below.

Option Name
© 2019 Devart

Description

900

SQL Server Data Access Components

AutoShrinkThreshold
CompactVersion
DefaultLockEscalation
DefaultLockTimeout
FlushInterval
ForceCreateDatabase
LocaleIdentifier
MaxBufferSize
MaxDatabaseSize
TempFileDirectory
TempFileMaxSize© 1997-2019
Devart. All Rights
Reserved.

Request Support

Specifies the amount of free space in the
database file before automatic shrink
starts.
Specifies which version of SQL Server
Compact will be used.
Specifies how many locks should be
performed before trying escalation fromrow to page or from page to table.
Specifies how much time in milliseconds atransaction will wait for a lock.
Specifies the interval at which committed
transactions are flushed to disk.
Used to force TMSCompactConnection tocreate a new database before opening aconnection, if the database is not exists.
Used to specify the preferable locale ID.
Specifies how much memory SQL Server
Compact Edition can use before flushingchanges to disk.
Specified maximum size of the main
database file.
Specifies the temp file directory.
Specified maximum size of the temporary
database file.
DAC Forum

Provide Feedback

5.15.1.1.2.6 TransactionCommitMode Property

Used to specify the way the buffer pool will be flushed on transaction commit.

Class
TMSCompactConnection

Syntaxproperty TransactionCommitMode: TCompactCommitMode default
DefaultTransactionCommitMode;

Remarks
Specifies in what way the buffer pool will be flushed on transaction commit.

© 1997-2019

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference901

Devart. All Rights
Reserved.
5.15.1.2 TMSCompactConnectionOptions ClassThis class allows setting up the behaviour of the TMSCompactConnection class.
For a list of all members of this type, see TMSCompactConnectionOptions members.

Unit
MSCompactConnection

SyntaxTMSCompactConnectionOptions = class(TCustomMSConnectionOptions);

Inheritance Hierarchy
TDAConnectionOptions
TCustomMSConnectionOptions
TMSCompactConnectionOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.1 Members

TMSCompactConnectionOptions class overview.

Properties
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)
AutoShrinkThreshold

CompactVersion

DefaultLockEscalation© 2019 Devart

Description
Specifies whether to allow or
not implicit connection
opening.
Specifies the amount of freespace in the database file
before automatic shrink
starts.
Specifies which version of
SQL Server Compact will be
used.
Specifies how many locks
should be performed before
trying escalation from row topage or from page to table.

902

SQL Server Data Access Components

Specifies how much time inmilliseconds a transaction
will wait for a lock.
Used to determine thedefault type of local sortingfor string fields. It is used
DefaultSortType (inherited fromwhen a sort type is not
TDAConnectionOptions)specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa
mes property of a dataset.
Used to open a connection
only when needed for
DisconnectedMode (inherited fromperforming a server call and
TDAConnectionOptions)closes after performing theoperation.
Specifies if data should be
Encrypt (inherited fromencrypted before sending it
TCustomMSConnectionOptions)over the network.
Specifies the interval atwhich committed
FlushIntervaltransactions are flushed to
disk.
Used to force
TMSCompactConnection tocreate a new database
ForceCreateDatabase
before opening aconnection, if the databaseis not exists.
Used to prevent an
KeepDesignConnected (inherited fromapplication from establishing
TDAConnectionOptions)a connection at the time ofstartup.
Used to specify the
LocaleIdentifier
preferable locale ID.
If True, theTCustomDAConnection.On
LocalFailover (inherited from TDAConnectionOptions) ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.
Specifies how muchmemory SQL Server
MaxBufferSize
Compact Edition can use
before flushing changes to
DefaultLockTimeout© 2019 DevartReference

disk.
Specified maximum size ofthe main database file.
Specifies the format ofstoring and representing the
NUMERIC (DECIMAL) fields
for all TCustomMSDataSets
associated with the given
connection.
Used to specify a provider
from the list of supported
providers.
Causes Microsoft SQL
Server to follow the SQL-92
rules regarding quotation
mark delimiting identifiers
and literal strings.
Specifies the temp file
directory.
Specified maximum size ofthe temporary database file.
Used to manage field typecreation for the NTEXT data
type.

MaxDatabaseSize

NumericType (inherited fromTCustomMSConnectionOptions)

Provider (inherited fromTCustomMSConnectionOptions)
QuotedIdentifier (inherited fromTCustomMSConnectionOptions)
TempFileDirectory
TempFileMaxSize
UseWideMemos (inherited fromTCustomMSConnectionOptions)© 1997-2019
Devart. All Rights
Reserved.

Request Support

903

DAC Forum

Provide Feedback

5.15.1.2.2 Properties

Properties of the TMSCompactConnectionOptions class.
For a complete list of the TMSCompactConnectionOptions class members, see the
TMSCompactConnectionOptions Members topic.

PublicName

DefaultSortType (inherited from
TDAConnectionOptions)© 2019 Devart

Description
Used to determine thedefault type of local sortingfor string fields. It is used
when a sort type is not
specified explicitly after thefield name in the
TMemDataSet.IndexFieldNa

904

SQL Server Data Access Components

mes property of a dataset.
Used to open a connection
only when needed for
DisconnectedMode (inherited fromperforming a server call and
TDAConnectionOptions)closes after performing theoperation.
Specifies if data should be
Encrypt (inherited fromencrypted before sending it
TCustomMSConnectionOptions)over the network.
Used to prevent an
KeepDesignConnected (inherited fromapplication from establishing
TDAConnectionOptions)a connection at the time ofstartup.
If True, theTCustomDAConnection.On
LocalFailover (inherited from TDAConnectionOptions) ConnectionLost event
occurs and a failover
operation can be performed
after connection breaks.
Specifies the format ofstoring and representing the
NumericType (inherited fromNUMERIC (DECIMAL) fields
TCustomMSConnectionOptions)for all TCustomMSDataSets
associated with the given
connection.
Used to specify a provider
Provider (inherited fromfrom the list of supported
TCustomMSConnectionOptions)providers.
Causes Microsoft SQL
Server to follow the SQL-92
QuotedIdentifier (inherited fromrules regarding quotation
TCustomMSConnectionOptions)mark delimiting identifiers
and literal strings.
Used to manage field type
UseWideMemos (inherited fromcreation for the NTEXT data
TCustomMSConnectionOptions)
type.

Published
Name
AllowImplicitConnect (inherited from
TDAConnectionOptions)
AutoShrinkThreshold

Description
Specifies whether to allow or
not implicit connection
opening.
Specifies the amount of free
© 2019 DevartReference

905

space in the database file
before automatic shrink
starts.
Specifies which version of
SQL Server Compact will be
used.
Specifies how many locks
should be performed before
trying escalation from row topage or from page to table.
Specifies how much time inmilliseconds a transaction
will wait for a lock.
Specifies the interval atwhich committed
transactions are flushed to
disk.
Used to force
TMSCompactConnection tocreate a new database
before opening aconnection, if the databaseis not exists.
Used to specify thepreferable locale ID.
Specifies how muchmemory SQL Server
Compact Edition can use
before flushing changes to
disk.
Specified maximum size ofthe main database file.
Specifies the temp file
directory.
Specified maximum size ofthe temporary database file.

CompactVersion

DefaultLockEscalation

DefaultLockTimeout

FlushInterval

ForceCreateDatabase

LocaleIdentifier

MaxBufferSize

MaxDatabaseSize
TempFileDirectory
TempFileMaxSize

See Also
TMSCompactConnectionOptions ClassTMSCompactConnectionOptions Class Members© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

906

SQL Server Data Access Components

5.15.1.2.2.1 AutoShrinkThreshold Property

Specifies the amount of free space in the database file before automatic shrink starts.

Class
TMSCompactConnectionOptions

Syntaxproperty AutoShrinkThreshold: integer default
DefaultAutoShrinkThreshold;

Remarks
Use the AutoShrinkThreshold property to specify the amount of free space in the database file
before automatic shrink starts. Measured in percents. The default value is 60.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.2 CompactVersion Property

Specifies which version of SQL Server Compact will be used.

Class
TMSCompactConnectionOptions

Syntaxproperty CompactVersion: TCompactVersion;

Remarks
Use the CompactVersion property to specify which version of SQL Server Compact will be
used. Useful when there are SQL Server Compact 3.0 and 3.5 installed on the same
computer. The default value is cvAuto. It means that if both server versions were installed
simultaneously, SQL Server Compact 3.5 will be used.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.3 DefaultLockEscalation Property

Specifies how many locks should be performed before trying escalation from row to page orfrom page to table.

© 2019 DevartReference

907

Class
TMSCompactConnectionOptions

Syntaxproperty DefaultLockEscalation: integer default
DefaultDefaultLockEscalation;

Remarks
Use the DefaultLockEscalation property to specify how many locks should be performed
before trying escalation from row to page or from page to table. The default value is 100.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.4 DefaultLockTimeout Property

Specifies how much time in milliseconds a transaction will wait for a lock.

Class
TMSCompactConnectionOptions

Syntaxproperty DefaultLockTimeout: integer;

Remarks
Use the DefaultLockTimeout property to specify how much time in milliseconds a transaction
will wait for a lock. The default value is 2000 ms.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.5 FlushInterval Property

Specifies the interval at which committed transactions are flushed to disk.

Class
TMSCompactConnectionOptions

Syntax© 2019 Devart

908

SQL Server Data Access Components

property FlushInterval: integer default DefaultFlushInterval;

Remarks
Use the FlushInterval property to specify the interval at which committed transactions areflushed to disk. Measured in seconds. The default value is 10.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.6 ForceCreateDatabase Property

Used to force TMSCompactConnection to create a new database before opening aconnection, if the database is not exists.

Class
TMSCompactConnectionOptions

Syntaxproperty ForceCreateDatabase: boolean;

Remarks
By default, when connecting to a database, SQL Server does not check whether there exists
the specified file. If the TMSCompactConnection.Database property points to a non-existent
database in correct system path, a new empty database will be created and opened, and no
warning message will be displayed. In the case if an incorrect database name was entered by
mistake, this behavior can lead to misunderstandings and errors in the operation of thesoftware.
If the TMSCompactConnectionOptions.ForceDatabaseCreate property is set to False, before
establishing a connection to the database, TMSCompactConnection will check whether the
specified file exists. If the file does not exist, an appropriate exception will be raised.
If the TMSConnectionOptions.ForceDatabaseCreate property is set to True, no checking will
be performed and a new database will be created.
The default value of the TMSCompactConnectionOptions.ForceCreateDatabase property is
False.
The default value of the TMSConnectionOptions.ForceDatabaseCreate property is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference909

5.15.1.2.2.7 LocaleIdentifier Property

Used to specify the preferable locale ID.

Class
TMSCompactConnectionOptions

Syntaxproperty LocaleIdentifier: string stored False;

Remarks
Use the LocaleIdentifier property to specify the locale ID. The default value is the systemdefault locale. LocaleIdentifier can be set using either locale ID:
MSCompactConnection.Options.LocaleIdentifier := '1033';, or locale name:
MSCompactConnection.Options.LocaleIdentifier := 'English (United States)';
It is better to use locale IDs because locale names may be different on different Windows
versions.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.8 MaxBufferSize Property

Specifies how much memory SQL Server Compact Edition can use before flushing changes
to disk.

Class
TMSCompactConnectionOptions

Syntaxproperty MaxBufferSize: integer default DefaultMaxBufferSize;

Remarks
Use the MaxBufferSize property to specify how much memory SQL Server Compact Edition
can use before flushing changes to disk. Measured in kilobytes. The default value is 640.

© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

910

SQL Server Data Access Components

Reserved.
5.15.1.2.2.9 MaxDatabaseSize Property

Specified maximum size of the main database file.

Class
TMSCompactConnectionOptions

Syntaxproperty MaxDatabaseSize: integer default DefaultMaxDatabaseSize;

Remarks
Specified maximum size of the main database file. Measured in megabytes. The default value
is 128.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.10 TempFileDirectory Property

Specifies the temp file directory.

Class
TMSCompactConnectionOptions

Syntaxproperty TempFileDirectory: string;

Remarks
Use the TempFileDirectory property to specify the temp file directory. If this option is not
assigned, the current database is used as a temporary database.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.15.1.2.2.11 TempFileMaxSize Property

Specified maximum size of the temporary database file.

Class© 2019 DevartReference

911

TMSCompactConnectionOptions

Syntaxproperty TempFileMaxSize: integer default DefaultTempFileMaxSize;

Remarks
Specified maximum size of the temporary database file. Measured in megabytes. The default
value is 128.

© 1997-2019
Devart. All Rights
Reserved.

5.16

Request Support

DAC Forum

Provide Feedback

MSConnectionPool
This unit contains the TMSConnectionPoolManager class for managing connection pool.

ClassesName

Description
A class of methods that areused for managing SDAC
connection pool.

TMSConnectionPoolManager© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.16.1 Classes
Classes in the MSConnectionPool unit.

ClassesName

Description
A class of methods that areused for managing SDAC
connection pool.

TMSConnectionPoolManager© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

912

SQL Server Data Access Components

5.16.1.1 TMSConnectionPoolManager ClassA class of methods that are used for managing SDAC connection pool.
For a list of all members of this type, see TMSConnectionPoolManager members.

Unit
MSConnectionPool

SyntaxTMSConnectionPoolManager = class(TCRConnectionPoolManager);

Remarks
Use the TMSConnectionPoolManager methods to manage SDAC connection pool.

Inheritance Hierarchy
TCRConnectionPoolManager
TMSConnectionPoolManager

See Also
Connection Pooling© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.16.1.1.1 Members

TMSConnectionPoolManager class overview.

© 1997-2019
Devart. All Rights
Reserved.

5.17

Request Support

DAC Forum

Provide Feedback

MSDumpThis unit contains implementation of the TMSDump component.

ClassesName

Description

TMSDump

The class that serves forstoring data from tables oreditable views as a script
and for restoring data from a© 2019 DevartReference

received script.
This class allows setting up
the behaviour of the
TMSDump class.

TMSDumpOptions© 1997-2019
Devart. All Rights
Reserved.

913

Request Support

DAC Forum

Provide Feedback

5.17.1 Classes
Classes in the MSDump unit.

ClassesName

Description
The class that serves forstoring data from tables oreditable views as a script
and for restoring data from a
received script.
This class allows setting up
the behaviour of the
TMSDump class.

TMSDump

TMSDumpOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.1 TMSDump Class

The class that serves for storing data from tables or editable views as a script and forrestoring data from a received script.
For a list of all members of this type, see TMSDump members.

Unit
MSDumpSyntaxTMSDump = class(TDADump);

Remarks
TMSDump serves to store data from tables or editable views as a script and to restore datafrom a received script.
© 2019 Devart

914

SQL Server Data Access Components

Use the TDADump.TableNames property to specify the list of objects to be stored. To launcha generating script, call the TDADump.Backup method.
TMSDump also can generate scripts for a query. Just call the TDADump.BackupQuery
method and pass a query statement into it. The object list assigned to the TableNames
property is ignored if you call TDADump.BackupQuery. The generated script can be viewed in
the TDADump.SQL property.
TMSDump works on the client side. It causes large network loading.

Inheritance Hierarchy
TDADump
TMSDump

See Also
TDADump.Backup
TDADump.Restore© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.1.1 Members

TMSDump class overview.

Properties
Name
Connection

Debug (inherited from TDADump)

Options
SQL (inherited from TDADump)
TableNames (inherited from TDADump)

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the
behaviour of a TMSDumpobject.
Used to set or get the dump
script.
Used to set the names of thetables to dump.

© 2019 DevartReference

915

Methods
Name
Backup (inherited from TDADump)
BackupQuery (inherited from TDADump)
BackupToFile (inherited from TDADump)
BackupToStream (inherited from TDADump)
Restore (inherited from TDADump)

Description
Dumps database objects to
the TDADump.SQL
property.
Dumps the results of aparticular query.
Dumps database objects tothe specified file.
Dumps database objects tothe stream.
Executes a script containedin the SQL property.

RestoreFromFile (inherited from TDADump)

Executes a script from a file.

RestoreFromStream (inherited from TDADump)

Executes a script received
from the stream.

EventsName

OnBackupProgress (inherited from TDADump)

OnError (inherited from TDADump)

OnRestoreProgress (inherited from TDADump)© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Description
Occurs to indicate the
TDADump.Backup,
M:Devart.Dac.TDADump.Ba
ckupToFile(System.String)or
M:Devart.Dac.TDADump.Ba
ckupToStream(Borland.Vcl.
TStream) method execution
progress.
Occurs when SQL Server
raises some error on
TDADump.Restore.
Occurs to indicate the
TDADump.Restore,
TDADump.RestoreFromFile, or
TDADump.RestoreFromStr
eam method execution
progress.
Provide Feedback

916

SQL Server Data Access Components

Reserved.
5.17.1.1.2 Properties

Properties of the TMSDump class.
For a complete list of the TMSDump class members, see the TMSDump Members topic.

Published
Name

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to display executing
statement, all its parameters'
values, and the type ofparameters.
Used to specify the
behaviour of a TMSDumpobject.
Used to set or get the dump
script.
Used to set the names of thetables to dump.

Connection

Debug (inherited from TDADump)

Options
SQL (inherited from TDADump)
TableNames (inherited from TDADump)

See Also
TMSDump ClassTMSDump Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.1.2.1 Connection Property

Used to specify a connection object that will be used to connect to a data store.

Class
TMSDump

Syntaxproperty Connection: TMSConnection;© 2019 DevartReference

917

Remarks
Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of the provided TMSConnection objects.
At runtime, set the Connection property to reference an existing TMSConnection object.

See Also
TMSConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.1.2.2 Options Property

Used to specify the behaviour of a TMSDump object.

Class
TMSDump

Syntaxproperty Options: TMSDumpOptions;Remarks
Set the properties of Options to specify the behaviour of a TMSDump object.
Descriptions of all options are in the table below.

Option Name

Description
Allows to disable foreign keys when
dumping multiple tables.
Used to add SET IDENTITY_INSERTTableName ON at the beginning of thescript and SET IDENTITY_INSERTTableName OFF at the end of the script.

DisableConstraints

IdentityInsert© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.2 TMSDumpOptions ClassThis class allows setting up the behaviour of the TMSDump class.
For a list of all members of this type, see TMSDumpOptions members.
© 2019 Devart

918

SQL Server Data Access Components

Unit
MSDumpSyntaxTMSDumpOptions = class(TDADumpOptions);

Inheritance Hierarchy
TDADumpOptions
TMSDumpOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.2.1 Members

TMSDumpOptions class overview.

Properties
Name
AddDrop (inherited from TDADumpOptions)

CompleteInsert (inherited from TDADumpOptions)

DisableConstraints
GenerateHeader (inherited from TDADumpOptions)

IdentityInsert

QuoteNames (inherited from TDADumpOptions)

Description
Used to add drop
statements to a script before
creating statements.
Used to explicitly specify thetable fields names whengenerating the INSERT SQL
query. The default value isFalse.
Allows to disable foreign
keys when dumping multiple
tables.
Used to add a comment
header to a script.
Used to add SET
IDENTITY_INSERTTableName ON at the
beginning of the script andSET IDENTITY_INSERTTableName OFF at the endof the script.
Used for TDADump to quote
all database object names in© 2019 DevartReference919

generated SQL statements.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.2.2 Properties

Properties of the TMSDumpOptions class.
For a complete list of the TMSDumpOptions class members, see the TMSDumpOptions
Members topic.

Published
Name
AddDrop (inherited from TDADumpOptions)

CompleteInsert (inherited from TDADumpOptions)

DisableConstraints
GenerateHeader (inherited from TDADumpOptions)

IdentityInsert

QuoteNames (inherited from TDADumpOptions)

Description
Used to add drop
statements to a script before
creating statements.
Used to explicitly specify thetable fields names whengenerating the INSERT SQL
query. The default value isFalse.
Allows to disable foreign
keys when dumping multiple
tables.
Used to add a comment
header to a script.
Used to add SET
IDENTITY_INSERTTableName ON at the
beginning of the script andSET IDENTITY_INSERTTableName OFF at the endof the script.
Used for TDADump to quote
all database object names ingenerated SQL statements.

See Also
TMSDumpOptions ClassTMSDumpOptions Class Members© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

920

SQL Server Data Access Components

Reserved.
5.17.1.2.2.1 DisableConstraints Property

Allows to disable foreign keys when dumping multiple tables.

Class
TMSDumpOptions

Syntaxproperty DisableConstraints: boolean default False;

Remarks
Use the DisableConstraints property to disable foreign keys when dumping multiple tables.
The default value is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.17.1.2.2.2 IdentityInsert Property

Used to add SET IDENTITY_INSERT TableName ON at the beginning of the script and SET
IDENTITY_INSERT TableName OFF at the end of the script.

Class
TMSDumpOptions

Syntaxproperty IdentityInsert: boolean default False;

Remarks
Use the IdentityInsert property to add SET IDENTITY_INSERT TableName ON at the
beginning of the script and SET IDENTITY_INSERT TableName OFF at the end of the script.
The first line allows explicit values to be inserted into the identity column of a table andINSERT statements are generated with IDENTITY field values. Otherwise the IDENTITY field
will not be included to the INSERT statements. SET IDENTITY_INSERT will not be added
while the option is ON if the table does not have a field identified as IDENTITY or there are norecords in the table.

© 1997-2019
Devart. All Rights

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

921

Reserved.

5.18

MSLoaderThis unit contains implementation of the TMSLoader component.

ClassesName

Description
A component representing
the attributes for column
loading.
TMSLoader allows to load
external data into the server
database.
This class allows setting up
the behaviour of the
TMSLoader class.

TMSColumn

TMSLoader

TMSLoaderOptions

Types
Name

Description
This type is used for the
TMSLoader.OnPutData
event.

TMSPutDataEvent© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1 Classes
Classes in the MSLoader unit.

ClassesName
TMSColumn

TMSLoader
TMSLoaderOptions© 2019 Devart

Description
A component representing
the attributes for column
loading.
TMSLoader allows to load
external data into the server
database.
This class allows setting up
the behaviour of the922

SQL Server Data Access Components

TMSLoader class.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.1 TMSColumn Class

A component representing the attributes for column loading.
For a list of all members of this type, see TMSColumn members.

Unit
MSLoaderSyntaxTMSColumn = class(TDAColumn);

Remarks
Each TMSLoader uses TDAColumns to maintain a collection of TMSColumn objects.
TMSColumn object represents the attributes for column loading. Every TMSColumn object
corresponds to one of the table fields with the same name as its TDAColumn.Name property.
To create columns at design-time use column editor of the TMSLoader component.

Inheritance Hierarchy
TDAColumn
TMSColumn

See Also
TMSLoader
TDAColumns© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.1.1 Members

TMSColumn class overview.

Properties
Name

Description© 2019 DevartReference

Used to specify the types ofvalues that will be loaded.
Used to specify the fieldname of loading table.
Defines the size used in thedefinition of the physicaldatabase field for the datatypes that support different
precision.
Used to set the scale ofnumeric values.
Used to set the size ofnumeric values.

FieldType (inherited from TDAColumn)
Name (inherited from TDAColumn)

Precision

Scale
Size
© 1997-2019
Devart. All Rights
Reserved.

Request Support

923

DAC Forum

Provide Feedback

5.18.1.1.2 Properties

Properties of the TMSColumn class.
For a complete list of the TMSColumn class members, see the TMSColumn Members topic.

Published
Name

Description
Used to specify the types ofvalues that will be loaded.
Used to specify the fieldname of loading table.
Defines the size used in thedefinition of the physicaldatabase field for the datatypes that support different
precision.
Used to set the scale ofnumeric values.
Used to set the size ofnumeric values.

FieldType (inherited from TDAColumn)
Name (inherited from TDAColumn)

Precision

Scale
Size

See Also
TMSColumn ClassTMSColumn Class Members© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

924

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.18.1.1.2.1 Precision Property

Defines the size used in the definition of the physical database field for the data types that
support different precision.

Class
TMSColumn

Syntaxproperty Precision: integer default 0;

Remarks
The Precision property can be filled automatically, when calling TDALoader.CreateColumns
or when setting the TDALoader.TableName property. User can manually create fields by filling
TMSColumn properties.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.1.2.2 Scale Property

Used to set the scale of numeric values.

Class
TMSColumn

Syntaxproperty Scale: integer default 0;

Remarks
Use the Scale property to set the scale of numeric values.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference925

5.18.1.1.2.3 Size Property

Used to set the size of numeric values.

Class
TMSColumn

Syntaxproperty Size: integer;

Remarks
Use the Size property to set the size of numeric values.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2 TMSLoader ClassTMSLoader allows to load external data into the server database.
For a list of all members of this type, see TMSLoader members.

Unit
MSLoaderSyntaxTMSLoader = class(TDALoader);Remarks
TMSLoader serves for fast loading of data to the server. TMSLoader functionality is based on
the SQL Server memory-based bulk-copy operations using the IRowsetFastLoad interface.
Simultaneous loading into multiple tables is not supported. Data loading is performed withouttransactions.

Inheritance Hierarchy
TDALoader
TMSLoader

See Also
MSDN: IRowsetFastLoad Usage and Limitations© 2019 Devart

926

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.1 Members

TMSLoader class overview.

Properties
Name
Columns (inherited from TDALoader)

Connection (inherited from TDALoader)

KeepIdentity

KeepNulls

Options

TableName (inherited from TDALoader)

Description
Used to add a TDAColumn
object for each field that will
be loaded.
Used to specify
TCustomDAConnection inwhich TDALoader will be
executed.
Used to specify the way
IDENTITY column values
must be handled.
Used to specify the way
NULL values for columns
with a DEFAULT constraint
must be handled.
Used to specify the
behaviour of a TMSLoader
object.
Used to specify the name of
the table to which data will
be loaded.

Methods
Name
CreateColumns (inherited from TDALoader)
Load (inherited from TDALoader)
LoadFromDataSet (inherited from TDALoader)
PutColumnData (inherited from TDALoader)

Description
Creates TDAColumn
objects for all fields of thetable with the same nameas TDALoader.TableName.
Starts loading data.
Loads data from thespecified dataset.
Overloaded. Puts the valueof individual columns.
© 2019 DevartReference

927

EventsName

Description
Occurs when putting column
values.
Occurs if handling dataloading progress of the
TDALoader.LoadFromData
Set method is needed.
Occurs when putting loading
data by rows.

OnGetColumnData

OnProgress (inherited from TDALoader)

OnPutData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.2 Properties

Properties of the TMSLoader class.
For a complete list of the TMSLoader class members, see the TMSLoader Members topic.

PublicName
Columns (inherited from TDALoader)

Connection (inherited from TDALoader)

KeepIdentity

KeepNulls

TableName (inherited from TDALoader)

Published© 2019 Devart

Description
Used to add a TDAColumn
object for each field that will
be loaded.
Used to specify
TCustomDAConnection inwhich TDALoader will be
executed.
Used to specify the way
IDENTITY column values
must be handled.
Used to specify the way
NULL values for columns
with a DEFAULT constraint
must be handled.
Used to specify the name of
the table to which data will
be loaded.

928

SQL Server Data Access Components

Name

Description
Used to specify the
behaviour of a TMSLoader
object.

Options

See Also
TMSLoader ClassTMSLoader Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.2.1 KeepIdentity Property

Used to specify the way IDENTITY column values must be handled.

Class
TMSLoader

Syntaxproperty KeepIdentity: boolean;

Remarks
Use the KeepIdentity property to specify in what way IDENTITY column values must be
handled. If KeepIdentity is set to False, IDENTITY columns will be initialized by the server. Anyvalue assigned to such column in your application is ignored. If KeepIdentity is set to True, the
IDENTITY property will not be available for all IDENTITY fields accepting NULL. So in this caseunique values should be generated and assigned by the client application. The default value ofthe KeepIdentity property is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.2.2 KeepNulls Property

Used to specify the way NULL values for columns with a DEFAULT constraint must be
handled.

Class
TMSLoader© 2019 DevartReference

929

Syntaxproperty KeepNulls: boolean;

Remarks
If this option is set to False, each NULL value inserted into a field with a DEFAULT constraint
will be replaced with the default value. If KeepNulls is set to True, NULL values inserted into afield with a DEFAULT constraint will not be replaced with the default values. The default valueof the KeepNulls property is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.2.3 Options Property

Used to specify the behaviour of a TMSLoader object.

Class
TMSLoader

Syntaxproperty Options: TMSLoaderOptions;Remarks
Use the Options property to specify the behaviour of a TMSLoader object.
Descriptions of all options are in the table below.

Option Name

Description
Used to specify if the table constraints arechecked during loading.
Allows table triggers to be fired with
TMSLoader on SQL Server during
insertion, deactivated by default.
Used to specify the size of data in kilobytes
to load in a single batch.
Used to specify if the table-level lock is
performed while loading is in progress.
Used to specify the number of rows to loadin a single batch.

CheckConstraints
FireTrigger
KilobytesPerBatch
LockTable
RowsPerBatch© 1997-2019© 2019 Devart

Request Support

DAC Forum

Provide Feedback

930

SQL Server Data Access Components

Devart. All Rights
Reserved.
5.18.1.2.3 Events

Events of the TMSLoader class.
For a complete list of the TMSLoader class members, see the TMSLoader Members topic.

PublicName

Description
Occurs if handling dataloading progress of the
TDALoader.LoadFromData
Set method is needed.

OnProgress (inherited from TDALoader)

Published
Name

Description
Occurs when putting column
values.
Occurs when putting loading
data by rows.

OnGetColumnData
OnPutData

See Also
TMSLoader ClassTMSLoader Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.3.1 OnGetColumnData Event

Occurs when putting column values.

Class
TMSLoader

Syntaxproperty OnGetColumnData: TMSGetColumnDataEvent;Remarks© 2019 DevartReference931

Write the OnGetColumnData event handler to put column values. TMSLoader calls the
OnGetColumnData event handler for each column in the loop. Column points to a TMSLoader
object that corresponds to the current loading column. Use its Name or Index property toidentify what column is loading. The Row parameter indicates the current loading record.
TMSLoader increments the Row parameter when all columns of the current record areloaded. The first row is 1. Set IsEOF to True to stop data loading. Fill the Value parameter bycolumn values. To start loading call the TDALoader.Load method.
Another way to load data is using the OnPutData event.

See Also
OnPutData
TDALoader.Load
TDALoader.OnGetColumnData© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.2.3.2 OnPutData Event

Occurs when putting loading data by rows.

Class
TMSLoader

Syntaxproperty OnPutData: TMSPutDataEvent;Remarks
Write the OnPutData event handler to put loading data by rows. Note that rows should be
loaded from the first one in ascending order. To start loading call the TDALoader.Loadmethod.

See Also
TDALoader.PutColumnData
TDALoader.Load
OnGetColumnData
TDALoader.OnPutData© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

932

SQL Server Data Access Components

Reserved.
5.18.1.3 TMSLoaderOptions ClassThis class allows setting up the behaviour of the TMSLoader class.
For a list of all members of this type, see TMSLoaderOptions members.

Unit
MSLoaderSyntaxTMSLoaderOptions = class(TDALoaderOptions);

Inheritance Hierarchy
TDALoaderOptions
TMSLoaderOptions© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.3.1 Members

TMSLoaderOptions class overview.

Properties
Name
CheckConstraints

FireTrigger

KilobytesPerBatch

LockTable

RowsPerBatch

Description
Used to specify if the table
constraints are checked
during loading.
Allows table triggers to be
fired with TMSLoader on
SQL Server during insertion,
deactivated by default.
Used to specify the size ofdata in kilobytes to load in asingle batch.
Used to specify if the tablelevel lock is performed whileloading is in progress.
Used to specify the numberof rows to load in a single
batch.
© 2019 DevartReference

UseBlankValues (inherited from TDALoaderOptions)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

933

Forces SDAC to fill thebuffer with null values after
loading a row to the
database.
Provide Feedback

5.18.1.3.2 Properties

Properties of the TMSLoaderOptions class.
For a complete list of the TMSLoaderOptions class members, see the TMSLoaderOptions
Members topic.

PublicName
UseBlankValues (inherited from TDALoaderOptions)

Description
Forces SDAC to fill thebuffer with null values after
loading a row to the
database.

Published
Name
CheckConstraints

FireTrigger

KilobytesPerBatch

LockTable

RowsPerBatch

See Also© 2019 Devart

Description
Used to specify if the table
constraints are checked
during loading.
Allows table triggers to be
fired with TMSLoader on
SQL Server during insertion,
deactivated by default.
Used to specify the size ofdata in kilobytes to load in asingle batch.
Used to specify if the tablelevel lock is performed whileloading is in progress.
Used to specify the numberof rows to load in a single
batch.

934

SQL Server Data Access Components

TMSLoaderOptions ClassTMSLoaderOptions Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.3.2.1 CheckConstraints Property

Used to specify if the table constraints are checked during loading.

Class
TMSLoaderOptions

Syntaxproperty CheckConstraints: boolean default False;

Remarks
Use the CheckConstraints property to specify if the table constraints are checked duringloading. If this option is set to False, the table constraints are not checked. The default valueof the CheckConstraints option is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.3.2.2 FireTrigger Property

Allows table triggers to be fired with TMSLoader on SQL Server during insertion, deactivatedby default.

Class
TMSLoaderOptions

Syntaxproperty FireTrigger: boolean default False;© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference935

5.18.1.3.2.3 KilobytesPerBatch Property

Used to specify the size of data in kilobytes to load in a single batch.

Class
TMSLoaderOptions

Syntaxproperty KilobytesPerBatch: integer default 0;

Remarks
Use the KilobytesPerBatch option to specify the size of data in kilobytes to load in a single
batch. The default value of this option is Unknown.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.1.3.2.4 LockTable Property

Used to specify if the table-level lock is performed while loading is in progress.

Class
TMSLoaderOptions

Syntaxproperty LockTable: boolean default False;

Remarks
Use the LockTable property to specify if the table-level lock is performed while loading is inprogress. Setting this option to True should improve the performance greatly. If this option is
set to False, the locking behaviour is determined by the table option. The default value of the
LockTable option is False.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.18.1.3.2.5 Row sPerBatch Property

Used to specify the number of rows to load in a single batch.

Class© 2019 Devart

Provide Feedback

936

SQL Server Data Access Components

TMSLoaderOptions

Syntaxproperty RowsPerBatch: integer default 0;

Remarks
Use the RowsPerBatch property to specify the number of rows to load in a single batch.
Server optimizes loading according to this value. The default value of this option is Unknown.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.2 Types
Types in the MSLoader unit.

Types
Name

Description
This type is used for the
TMSLoader.OnPutData
event.

TMSPutDataEvent© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.18.2.1 TMSPutDataEvent Procedure ReferenceThis type is used for the TMSLoader.OnPutData event.

Unit
MSLoaderSyntax
TMSPutDataEvent = procedure (Sender: TMSLoader) of object;Parameters
SenderAn object that raised the event.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

5.19

937

MSScript
This unit contains implementation of the TMSScript component.

ClassesName

Description
A component for executing
several SQL statements one
by one.

TMSScript© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1 Classes
Classes in the MSScript unit.

ClassesName

Description
A component for executing
several SQL statements one
by one.

TMSScript© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1 TMSScript Class

A component for executing several SQL statements one by one.
For a list of all members of this type, see TMSScript members.

Unit
MSScript

SyntaxTMSScript = class(TDAScript);

Remarks
Often it is necessary to execute several SQL statements one by one. Known way is using a
lot of components such as TMSSQL. Usually it is not a good solution. With only one© 2019 Devart

938

SQL Server Data Access Components

TMSScript component you can execute several SQL statements as one. This sequence ofstatements is named script. To separate single statements use semicolon (;), slash (/) or
keyword 'GO' . Note that slash must be the first character in line.
Errors that occur while execution can be processed in the TDAScript.OnError event handler.
By default, on error TMSScript shows exception and continues execution.
If you need to create several Stored Procedures (Functions) at a single script, use slash (/) toseparate commands for creating stored procedures.

Inheritance Hierarchy
TDAScript
TMSScript

See Also
TMSSQL© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1.1 Members

TMSScript class overview.

Properties
Name
Connection

DataSetDebug (inherited from TDAScript)

Delimiter (inherited from TDAScript)

EndLine (inherited from TDAScript)
EndOffset (inherited from TDAScript)

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to retrieve the resultsof the SELECT statements
execution inside a script.
Used to display the script
execution and all its
parameter values.
Used to set the delimiter
string that separates script
statements.
Used to get the current
statement last line number ina script.
Used to get the offset in the© 2019 DevartReference

EndPos (inherited from TDAScript)
Macros (inherited from TDAScript)
SQL (inherited from TDAScript)
StartLine (inherited from TDAScript)

StartOffset (inherited from TDAScript)

StartPos (inherited from TDAScript)

Statements (inherited from TDAScript)
UseOptimization

939

last line of the current
statement.
Used to get the end positionof the current statement.
Used to change SQL script
text in design- or run-timeeasily.
Used to get or set script text.
Used to get the current
statement start line number
in a script.
Used to get the offset in thefirst line of the current
statement.
Used to get the start positionof the current statement in ascript.
Contains a list of statements
obtained from the SQL
property.
Used to bind small queriesin blocks for block executing.

Methods
Name
BreakExec (inherited from TDAScript)
ErrorOffset (inherited from TDAScript)
Execute (inherited from TDAScript)
ExecuteFile (inherited from TDAScript)
ExecuteNext (inherited from TDAScript)
ExecuteStream (inherited from TDAScript)
MacroByName (inherited from TDAScript)© 2019 Devart

Description
Stops script execution.
Used to get the offset of thestatement if the Execute
method raised an exception.
Executes a script.
Executes SQL statements
contained in a file.
Executes the next statementin the script and then stops.
Executes SQL statements
contained in a stream
object.
Finds a Macro with thename passed in Name.

940

SQL Server Data Access Components

EventsName

Description
Occurs after a SQL script
execution.
Occurs when taking a
specific action before
executing the current SQL
statement is needed.
Occurs when SQL Server
raises an error.

AfterExecute (inherited from TDAScript)

BeforeExecute (inherited from TDAScript)

OnError (inherited from TDAScript)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1.2 Properties

Properties of the TMSScript class.
For a complete list of the TMSScript class members, see the TMSScript Members topic.

PublicName
EndLine (inherited from TDAScript)

EndOffset (inherited from TDAScript)
EndPos (inherited from TDAScript)
StartLine (inherited from TDAScript)

StartOffset (inherited from TDAScript)

StartPos (inherited from TDAScript)

Statements (inherited from TDAScript)

Description
Used to get the current
statement last line number ina script.
Used to get the offset in thelast line of the current
statement.
Used to get the end positionof the current statement.
Used to get the current
statement start line number
in a script.
Used to get the offset in thefirst line of the current
statement.
Used to get the start positionof the current statement in ascript.
Contains a list of statements
obtained from the SQL
property.

© 2019 DevartReference

941

Published
Name

Description
Used to specify aconnection object that will be
used to connect to a datastore.
Used to retrieve the resultsof the SELECT statements
execution inside a script.
Used to display the script
execution and all its
parameter values.
Used to set the delimiter
string that separates script
statements.
Used to change SQL script
text in design- or run-timeeasily.

Connection

DataSetDebug (inherited from TDAScript)

Delimiter (inherited from TDAScript)

Macros (inherited from TDAScript)
SQL (inherited from TDAScript)

Used to get or set script text.

UseOptimization

Used to bind small queriesin blocks for block executing.

See Also
TMSScript Class
TMSScript Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1.2.1 Connection Property

Used to specify a connection object that will be used to connect to a data store.

Class
TMSScript

Syntaxproperty Connection: TCustomMSConnection;

Remarks© 2019 Devart

942

SQL Server Data Access Components

Use the Connection property to specify a connection object that will be used to connect to adata store.
Set at design-time by selecting from the list of provided TMSConnection objects.
At run-time, set the Connection property to reference an existing TMSConnection object.

See Also
TMSConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1.2.2 DataSet Property

Used to retrieve the results of the SELECT statements execution inside a script.

Class
TMSScript

Syntaxproperty DataSet: TCustomMSDataSet;

Remarks
Set the DataSet property if you need to retrieve the results of the SELECT statements
execution inside a script.

See Also
TDAScript.Execute© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.19.1.1.2.3 UseOptimization Property

Used to bind small queries in blocks for block executing.

Class
TMSScript

Syntaxproperty UseOptimization: boolean;© 2019 DevartReference

943

Remarks
If the UseOptimization property is set, small queries will be united into blocks for block
executing if possible. The UseOptimization option does not affect the TDAScript.ExecuteNext
method performance. It works only for the TDAScript.Execute method.

© 1997-2019
Devart. All Rights
Reserved.

5.20

Request Support

DAC Forum

Provide Feedback

MSServiceBroker
This unit contains implementation of the TMSServiceBroker component and auxiliary classes.

ClassesName

Description
A base class that describes
the dialog process between
two services.
A class representing aService Broker message ofMicrosoft SQL Server.
A component that provides
sending and receiving
messages within the Service
Broker system.

TMSConversation

TMSMessage

TMSServiceBroker

Enumerations
Name

Description
Defines the type ofvalidation performed.

TMSMessageValidation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1 Classes
Classes in the MSServiceBroker unit.

ClassesName© 2019 Devart

Description

944

SQL Server Data Access Components

A base class that describes
the dialog process between
two services.
A class representing aService Broker message ofMicrosoft SQL Server.
A component that provides
sending and receiving
messages within the Service
Broker system.

TMSConversation

TMSMessage

TMSServiceBroker© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1 TMSConversation ClassA base class that describes the dialog process between two services.
For a list of all members of this type, see TMSConversation members.

Unit
MSServiceBroker

SyntaxTMSConversation = class(System.TObject);Remarks
The TMSConversation class describes the dialog process between two services.
To start a new conversation, use the TMSServiceBroker.BeginDialog method. You can finish
the dialog by calling the TMSConversation.EndConversation method.
Note: You should not create and delete TMSConversation objects by calling the Create andFree methods directly. Use the TMSServiceBroker.BeginDialog and
TMSConversation.EndConversation methods instead.

See Also
TMSMessage
TMSServiceBroker
TMSServiceBroker.Conversations© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference945

5.20.1.1.1 Members

TMSConversation class overview.

Properties
Name
ContractName
FarService
GroupId
HandleIsInitiator

ServiceBroker

Description
Stores the contact name theconversation conforms to.
Holds the service name ofthe second side taking partin the dialog.
Holds the unique identifier ofa conversation group.
Holds a unique identifier ofthe current conversation.
Determines if theconversation was initiatedby this side.
Determines the
TMSServiceBroker object towhich a conversation
instance belongs.

Methods
Name
BeginTimer

EndConversation
EndConversationWithError
GetTransmissionStatus
Send
SendEmpty© 2019 Devart

Description
Provides a message of the
SDialogTimerTypemessage type after the time
specified in the Timeout
property has been expired.
Terminates theconversation.
Terminates the conversationand provides the text andcode of the error.
Returns the status of the lastsent message.
Overloaded. Sends a
message within aconversation.
Sends an empty message
within a conversation.

946

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.2 Properties

Properties of the TMSConversation class.
For a complete list of the TMSConversation class members, see the TMSConversation
Members topic.

PublicName

Description
Stores the contact name theconversation conforms to.
Holds the service name ofthe second side taking partin the dialog.
Holds the unique identifier ofa conversation group.
Holds a unique identifier ofthe current conversation.
Determines if theconversation was initiatedby this side.
Determines the
TMSServiceBroker object towhich a conversation
instance belongs.

ContractName
FarService
GroupId
HandleIsInitiator

ServiceBroker

See Also
TMSConversation ClassTMSConversation Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.2.1 ContractName Property

Stores the contact name the conversation conforms to.

Class
TMSConversation© 2019 DevartReference

947

Syntaxproperty ContractName: string;

Remarks
Stores the name of the contract that the conversation conforms to.

See Also
TMSServiceBroker.BeginDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.2.2 FarService Property

Holds the service name of the second side taking part in the dialog.

Class
TMSConversation

Syntaxproperty FarService: string;

Remarks
The service name of the second side that is taking part in the dialog.

See Also
TMSServiceBroker.Service© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.20.1.1.2.3 GroupId Property

Holds the unique identifier of a conversation group.

Class
TMSConversation

Syntax© 2019 Devart

Provide Feedback

948

SQL Server Data Access Components

property GroupId: TGuid;

Remarks
Use the GroupId property to store a unique identifier of the conversation group. It is used forexecuting Transact-SQL queries.
The value of this property can be set when calling the TMSServiceBroker.BeginDialog methodwith the RelatedConversation or the GroupId parameter. If TMSServiceBroker.BeginDialog
was called with these parameters omitted, the GroupId will be assigned to the unique value.
If the conversation already exists, you can assign a new value for GroupId. See thedescription of the MOVE CONVERSATION statement in MSDN for details.

See Also
Handle© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.2.4 Handle Property

Holds a unique identifier of the current conversation.

Class
TMSConversation

Syntaxproperty Handle: TGuid;

Remarks
The Handle property stores a unique identifier of the current conversation. It is used forexecuting Transact-SQL queries. Handle is a read-only property.

See Also
GroupId© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference949

5.20.1.1.2.5 IsInitiator Property

Determines if the conversation was initiated by this side.

Class
TMSConversation

Syntaxproperty IsInitiator: boolean;

Remarks
Indicates whether the conversation was initiated by this side.

See Also
TMSServiceBroker.Service
TMSServiceBroker.BeginDialog
FarService© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.2.6 ServiceBroker Property

Determines the TMSServiceBroker object to which a conversation instance belongs.

Class
TMSConversation

Syntaxproperty ServiceBroker: TMSServiceBroker;

Remarks
Use the ServiceBroker property to identify the TMSServiceBroker object to which a
conversation instance belongs.

See Also
TMSServiceBroker.Conversations© 1997-2019
Devart. All Rights
Reserved.
© 2019 Devart

Request Support

DAC Forum

Provide Feedback

950

SQL Server Data Access Components

5.20.1.1.3 Methods

Methods of the TMSConversation class.
For a complete list of the TMSConversation class members, see the TMSConversation
Members topic.

PublicName

Description
Provides a message of the
SDialogTimerTypemessage type after the time
specified in the Timeout
property has been expired.
Terminates theconversation.
Terminates the conversationand provides the text andcode of the error.
Returns the status of the lastsent message.
Overloaded. Sends a
message within aconversation.
Sends an empty message
within a conversation.

BeginTimer

EndConversation
EndConversationWithError
GetTransmissionStatus
Send
SendEmpty

See Also
TMSConversation ClassTMSConversation Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.1 BeginTimer Method

Provides a message of the SDialogTimerType message type after the time specified in the
Timeout property has been expired.

Class
TMSConversation

Syntax© 2019 DevartReference

951

procedure BeginTimer(const Timeout: integer);
Parameters
Timeout
Specifies the amount of time to wait before displaying the message.

Remarks
Call the BeginTimer method to receive a message of the SDialogTimerType message typeafter the time specified in the Timeout property (in seconds) is expired.
See the description of the BEGIN CONVERSATION TIMER statement in MSDN for details.

See Also
TMSMessage
TMSServiceBroker.CurrentMessage© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.2 EndConversation Method

Terminates the conversation.

Class
TMSConversation

Syntax
procedure EndConversation(const Cleanup: boolean = False);
Parameters
Cleanup
True, if undelivered messages should be deleted. False otherwise.

Remarks
Call the EndConversation method to terminate a conversation. The Cleanup parameter
determines whether the undelivered massages will be deleted.
See the description of the END CONVERSATION statement in MSDN for details.

See Also
EndConversationWithError
TMSServiceBroker.BeginDialog© 2019 Devart

952

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.3 EndConversationWithError Method

Terminates the conversation and provides the text and code of the error.

Class
TMSConversation

Syntax
procedure EndConversationWithError(const ErrorMessage: string;
const ErrorCode: integer; const Cleanup: boolean = False);
Parameters
ErrorMessage
Holds the text of the error.
ErrorCode
Holds the code of the error.
Cleanup
True, if undelivered messages should be deleted. False otherwise.

Remarks
Use the EndConversationWithError method to terminate a conversation and handle the text
(ErrorMessage) and code (ErrorCode) of the error. The Cleanup parameter determines
whether the undelivered massages will be deleted.
See the description of the END CONVERSATION statement in MSDN for details.

See Also
EndConversationWithError
TMSServiceBroker.BeginDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.4 GetTransmissionStatus Method

Returns the status of the last sent message.

Class
TMSConversation© 2019 DevartReference

953

Syntaxfunction GetTransmissionStatus: string;
Return Valuethe status of the last sent message.

Remarks
Call the GetTransmissionStatus method to return the status of the last sent message.
See the description of the GET_TRANSMISSION_STATUS statement in MSDN for details.

See Also
TMSConversation.Send© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.5 Send Method

Sends a message within a conversation.

Class
TMSConversation

Overload List
Name
Description
Send(const MessageBody: TBytes; const
Sends a message within a conversation.
MessageType: string)Send(const MessageBody: string; const
Sends a message within a conversation.
MessageType: string)© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
Sends a message within a conversation.

Class
TMSConversation

Syntax© 2019 Devart

954

SQL Server Data Access Components

procedure Send(const MessageBody: TBytes; const MessageType:string = ''); overload;
Parameters
MessageBody
Holds the message to be sent.
MessageType
Determines the type of the message being sent.

Remarks
The Send method sends a message within a conversation. The target service is determinedwhen creating a conversation.
The MessageType parameter determines the type of the message being sent. For thedetailed message types description see the description of the CREATE MESSAGE TYPE
statement in MSDN.
You can check the status of the last sent message by the
TMSConversation.GetTransmissionStatus method.
Note: The method overload with the WideString MessageBody parameter type is notsupported under Delphi 5.

See Also
TMSConversation.GetTransmissionStatus
TMSConversation.SendEmpty
TMSMessage.AsString
TMSMessage.AsWideString
TMSMessage.AsBytes© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Sends a message within a conversation.

Class
TMSConversation

Syntax
procedure Send(const MessageBody: string; const MessageType:string = ''); overload;
Parameters© 2019 DevartReference

955

MessageBody
Holds the message to be sent.
MessageType
Determines the type of the message being sent.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.1.3.6 SendEmpty Method

Sends an empty message within a conversation.

Class
TMSConversation

Syntax
procedure SendEmpty(const MessageType: string = '');
Parameters
MessageType
Determines the type of the message being sent.

Remarks
Sends an empty message within a conversation. The target service is determined whencreating a conversation.
This method must be used to send an empty message. This is the only method that can beused to send a message if MessageType was created with the Validation property set to
mvEmpty.
The MessageType parameter determines the type of the message being sent. For thedetailed description of the message types see the description of the CREATE MESSAGE
TYPE statement in MSDN.

See Also
TMSConversation.Send
TMSMessage.IsEmpty© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

956

SQL Server Data Access Components

5.20.1.2 TMSMessage ClassA class representing a Service Broker message of Microsoft SQL Server.
For a list of all members of this type, see TMSMessage members.

Unit
MSServiceBroker

SyntaxTMSMessage = class(System.TObject);Remarks
The TMSMessage class represents a Service Broker message of Microsoft SQL Server. Use
the TMSMessage class to retrieve the message body and parameters from the message
obtained from a queue.
All properties of TMSMessage are read-only. Use the TMSConversation.Send method to senda message.
Each message belongs to a conversation.

See Also
TMSServiceBroker
TMSServiceBroker.CurrentMessage© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.1 Members

TMSMessage class overview.

Properties
Name
AsBytes
AsString
AsWideString
Conversation

Description
Used to read message bodyas an array of bytes.
Used to read message bodyas an ANSI string.
Used to read message bodyas a Unicode string.
Used to get a link to the
TMSConversation object
that belongs to the© 2019 DevartReference

message.
Used to ascertain whether amessage contains a value.
Holds the sequence numberof a message within aconversation.
Used to store the name of
the message type that
describes the message.
Used to store the ordernumber of a message withina queue.
Validation for the message
to be performed by theserver.

IsEmpty
MessageSequenceNumber

MessageType

QueuingOrder

Validation© 1997-2019
Devart. All Rights
Reserved.

Request Support

957

DAC Forum

Provide Feedback

5.20.1.2.2 Properties

Properties of the TMSMessage class.
For a complete list of the TMSMessage class members, see the TMSMessage Members
topic.

PublicName
AsBytes
AsString
AsWideString

Conversation

IsEmpty
MessageSequenceNumber© 2019 Devart

Description
Used to read message bodyas an array of bytes.
Used to read message bodyas an ANSI string.
Used to read message bodyas a Unicode string.
Used to get a link to the
TMSConversation object
that belongs to themessage.
Used to ascertain whether amessage contains a value.
Holds the sequence numberof a message within aconversation.

958

SQL Server Data Access Components

Used to store the name of
the message type that
describes the message.
Used to store the ordernumber of a message withina queue.
Validation for the message
to be performed by theserver.

MessageType

QueuingOrder

Validation

See Also
TMSMessage Class
TMSMessage Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.1 AsBytes Property

Used to read message body as an array of bytes.

Class
TMSMessage

Syntaxproperty AsBytes: TBytes;

Remarks
Use the AsBytes property to read message body as an array of bytes.

See Also
AsString
AsWideString
TMSConversation.Send
IsEmpty© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference959

5.20.1.2.2.2 AsString Property

Used to read message body as an ANSI string.

Class
TMSMessage

Syntaxproperty AsString: string;

Remarks
Use the AsString property to read message body as an ANSI string.
Note: If the body of the received message stores a Unicode string value or a TBytes value,
the result of AsString will be wrong.

See Also
AsWideString
AsBytes
TMSConversation.Send
IsEmpty© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.3 AsWideString Property

Used to read message body as a Unicode string.

Class
TMSMessage

Syntaxproperty AsWideString: string;

Remarks
Use the AsWideString property to read message body as a Unicode string.
Note: If the body of the received message stores an ANSI string value or a TBytes value, theresult of AsWideString will be wrong.

© 2019 Devart

960

SQL Server Data Access Components

See Also
AsString
AsBytes
TMSConversation.Send
IsEmpty© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.4 Conversation Property

Used to get a link to the TMSConversation object that belongs to the message.

Class
TMSMessage

Syntaxproperty Conversation: TMSConversation;

Remarks
Use the Conversation property to get a link to the TMSConversation object that belongs to themessage.

See Also
TMSConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.5 IsEmpty Property

Used to ascertain whether a message contains a value.

Class
TMSMessage

Syntaxproperty IsEmpty: boolean;

Remarks© 2019 DevartReference

961

Check the IsEmpty property to ascertain whether a message contains a value. If IsEmpty is
set to True, the message is blank, otherwise the message has a value.

See Also
TMSConversation.SendEmpty
AsString
AsWideString
AsBytes© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.6 MessageSequenceNumber Property

Holds the sequence number of a message within a conversation.

Class
TMSMessage

Syntaxproperty MessageSequenceNumber: Int64;

Remarks
Holds the sequence number of a message within a conversation.

See Also
QueuingOrder© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.7 MessageType Property

Used to store the name of the message type that describes the message.

Class
TMSMessage

Syntaxproperty MessageType: string;© 2019 Devart

962

SQL Server Data Access Components

Remarks
Use the MessageType property to store the name of the message type that describes themessage.
If the MessageType property was not set when sending, it has the DEFAULT value.

See Also
TMSConversation.Send© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.8 QueuingOrder Property

Used to store the order number of a message within a queue.

Class
TMSMessage

Syntaxproperty QueuingOrder: Int64;

Remarks
Use the QueuingOrder property to store the order number of a message within a queue.

See Also
MessageSequenceNumber© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.2.2.9 Validation Property

Validation for the message to be performed by the server.

Class
TMSMessage

Syntaxproperty Validation: TMSMessageValidation;© 2019 DevartReference

963

Remarks
Use the Validation property to validate the message to be performed by the server.

See Also
QueuingOrder
MessageSequenceNumber© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3 TMSServiceBroker Class

A component that provides sending and receiving messages within the Service Broker
system.
For a list of all members of this type, see TMSServiceBroker members.

Unit
MSServiceBroker

SyntaxTMSServiceBroker = class(TComponent);

Remarks
The TMSServiceBroker component lets you send and receive messages within the SQL
Server Service Broker system.
TMSServiceBroker supports synchronous and asynchronous messages receiving. Eachmessage belongs to a conversation.
Before using the Service Broker system with a database, you should activate Message
Delivery .

See Also
TMSConversation
TMSMessage
TCustomMSConnection© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

964

SQL Server Data Access Components

5.20.1.3.1 Members

TMSServiceBroker class overview.

Properties
Name
AsyncNotification

Connection

ConversationCount
Conversations
CurrentMessage

FetchRows

Queue

Service

WaitTimeout

Description
Used to receive messages
asynchronously in a
separate thread.
Used to specify aconnection object that will be
used to connect to theserver.
Conversations count in theConversations list.
Used for storing the list ofavailable conversations.
The current message
received by the Receive
method.
Used to determine theamount of rows that will bereceived from the server at atime.
This property determines
queue for the specified
service.
Used to set the service
name that will be used forsending and receiving
messages.
Used to specify the time towait until a message arrives
to the server.

Methods
Name
BeginDialog

Description
Overloaded. Initiates a
dialog from one
TMSServiceBroker.Service
to another service.

CreateServerObjects

Creates a service and a© 2019 DevartReference

965

queue on the server.
Removes both the service
with the name assigned totheTMSServiceBroker.Service
property and the queue with
the name
TMSServiceBroker.Service
name + '_Queue'.
Delivers contract name fromthe server.
Delivers the names ofmessage types from theserver.
Delivers queue names fromthe server.
Delivers queue names fromthe server.
Designed for receiving
messages from a queue on
the server from thespecified service.

DropServerObjects

GetContractNames
GetMessageTypeNames
GetQueueNames
GetServiceNames

Receive

EventsName

Description
Occurs when a new object of
the TMSConversation classis being created.
Occurs when an existing
conversation is being
closed.
Occurs when a newmessage is received in theasynchronous mode.

OnBeginConversation

OnEndConversation

OnMessage© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2 Properties

Properties of the TMSServiceBroker class.
For a complete list of the TMSServiceBroker class members, see the TMSServiceBroker
Members topic.
© 2019 Devart

966

SQL Server Data Access Components

PublicName

Description
Conversations count in theConversations list.
Used for storing the list ofavailable conversations.
The current message
received by the Receive
method.
This property determines
queue for the specified
service.

ConversationCount
Conversations
CurrentMessage

Queue

Published
Name

Description
Used to receive messages
asynchronously in a
separate thread.
Used to specify aconnection object that will be
used to connect to theserver.
Used to determine theamount of rows that will bereceived from the server at atime.
Used to set the service
name that will be used forsending and receiving
messages.
Used to specify the time towait until a message arrives
to the server.

AsyncNotification

Connection

FetchRows

Service

WaitTimeout

See Also
TMSServiceBroker Class
TMSServiceBroker Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

967

5.20.1.3.2.1 AsyncNotification Property

Used to receive messages asynchronously in a separate thread.

Class
TMSServiceBroker

Syntaxproperty AsyncNotification: boolean default False;

Remarks
If the AsyncNotification property is set to True, messages will be received asynchronously in a
separate thread. Each message receiving in asynchronous mode triggers the OnMessage
event. For working in asynchronous mode, an addition connection to the server is
automatically created.
The default value is False.

See Also
OnMessage
Receive© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.2 Connection Property

Used to specify a connection object that will be used to connect to the server.

Class
TMSServiceBroker

Syntaxproperty Connection: TMSConnection;

Remarks
Use the Connection property to specify a connection object that will be used to connect to theserver.
Set at design time by selecting from the list of available connection objects.
At runtime, set the Connection property to an instance of a TCustomMSConnection object.

© 2019 Devart

968

SQL Server Data Access Components

See Also
TCustomMSConnection© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.3 ConversationCount Property

Conversations count in the Conversations list.

Class
TMSServiceBroker

Syntaxproperty ConversationCount: integer;

Remarks
Conversations count in the Conversations list.

See Also
Conversations
BeginDialog
CurrentMessage
Receive
OnBeginConversation
OnEndConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.4 Conversations Property(Indexer)

Used for storing the list of available conversations.

Class
TMSServiceBroker

Syntaxproperty Conversations[Index: Integer]: TMSConversation; default;© 2019 DevartReference969

Parameters
Index
Indicates the index of the conversation object, where 0 is the index of the first object, 1 is theindex of the second object, and so on.

Remarks
This property stores the list of available conversations. A new conversation object can be
added to this list in two ways:
when calling the BeginDialog method;when receiving an incoming message.
Note: This list is not synchronized with the list on the server. For example, if an initiator has
created a conversation instance (by calling the BeginDialog method), a conversation instanceon the target side will be created only after receiving the first message.
Analogously, when receiving a message with the SEndDialogType or SErrorType message
type, the conversation on the server is already completed. But this conversation will be
removed from the list after the next call to the Receive method.

See Also
ConversationCount
BeginDialog
CurrentMessage
Receive
OnBeginConversation
OnEndConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.20.1.3.2.5 CurrentMessage Property

The current message received by the Receive method.

Class
TMSServiceBroker

Syntaxproperty CurrentMessage: TMSMessage;

Remarks© 2019 Devart

Provide Feedback

970

SQL Server Data Access Components

The current message received by the Receive method.

See Also
Conversations
BeginDialog
Receive
OnBeginConversation
OnEndConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.6 FetchRow s Property

Used to determine the amount of rows that will be received from the server at a time.

Class
TMSServiceBroker

Syntaxproperty FetchRows: integer default 0;

Remarks
Use the FetchRows property to determine the amount of rows that will be received from theserver at a time.

See Also
Receive
TMSMessage© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.7 Queue Property

This property determines queue for the specified service.

Class
TMSServiceBroker© 2019 DevartReference

971

Syntaxproperty Queue: string;

Remarks
This property determines queue for the specified service.

See Also
Service
GetQueueNames
MSDN: CREATE QUEUE© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.2.8 Service Property

Used to set the service name that will be used for sending and receiving messages.

Class
TMSServiceBroker

Syntaxproperty Service: string;

Remarks
Use the Service property to set the service name that will be used for sending and receiving
messages.

See Also
Queue
GetServiceNames
TMSConversation.FarService
MSDN: CREATE SERVICE© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

972

SQL Server Data Access Components

5.20.1.3.2.9 WaitTimeout Property

Used to specify the time to wait until a message arrives to the server.

Class
TMSServiceBroker

Syntaxproperty WaitTimeout: integer default - 1;

Remarks
If the Receive method was called and there are no messages on the server, it will wait until atleast one message arrives or WaitTimeout expires. The WaitTimeout is measured inmilliseconds.
The possible values of WaitTimeout are the following:

Value
-1
0
1 and more

Meaning
Do not wait (the default value).
Wait for an infinite interval while at least one message arrives.
Wait for the specified interval or until a message arrives.

See Also
Receive© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3 Methods

Methods of the TMSServiceBroker class.
For a complete list of the TMSServiceBroker class members, see the TMSServiceBroker
Members topic.

PublicName
BeginDialog

CreateServerObjects

Description
Overloaded. Initiates a
dialog from one
TMSServiceBroker.Service
to another service.
Creates a service and aqueue on the server.
© 2019 DevartReference

973

Removes both the service
with the name assigned totheTMSServiceBroker.Service
property and the queue with
the name
TMSServiceBroker.Service
name + '_Queue'.
Delivers contract name fromthe server.
Delivers the names ofmessage types from theserver.
Delivers queue names fromthe server.
Delivers queue names fromthe server.
Designed for receiving
messages from a queue on
the server from thespecified service.

DropServerObjects

GetContractNames
GetMessageTypeNames
GetQueueNames
GetServiceNames

Receive

See Also
TMSServiceBroker Class
TMSServiceBroker Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.1 BeginDialog Method

Initiates a dialog from one Service to another service.

Class
TMSServiceBroker

Overload List
Name
Description
BeginDialog(const TargetService: string;
const TargetDatabase: string; const
Initiates a dialog from one Service toanother service.
UseEncryption: boolean;
RelatedConversation: TMSConversation;© 2019 Devart

974

SQL Server Data Access Components

const LifeTime: integer; const Contract:
string)BeginDialog(const TargetService: string;
const TargetDatabase: string; const
Initiates a dialog from one Service to
UseEncryption: boolean; const GroupId:
another service.
TGuid; const LifeTime: integer; const
Contract: string)© 1997-2019
Request Support
DAC Forum
Provide Feedback
Devart. All Rights
Reserved.
Initiates a dialog from one TMSServiceBroker.Service to another service.

Class
TMSServiceBroker

Syntaxfunction BeginDialog(const TargetService: string; const
TargetDatabase: string = ''; const UseEncryption: boolean = True;
RelatedConversation: TMSConversation = nil; const LifeTime:
integer = 0; const Contract: string = ''): TMSConversation;
overload;
Parameters
TargetService
The target service name that the conversation initiates with.
TargetDatabase
Specifies the database name that the target service hosts.
UseEncryption
Specifies whether messages within the conversation must be encrypted. When set to True(the default value), it may require applying additional server settings.
RelatedConversation
Already existing conversation to whose group a new conversation will be added. If thisparameter is not set, a new group will be created.
LifeTime
Specifies the maximum time interval (in seconds) while the dialog remains open. After thisinterval expires, the dialog automatically closes. A zero LifeTime value represents an infinity
interval. This is the default value.
Contract
Specifies the name of the contract that the conversation conforms to. If the parameter is not
set, the DEFAULT contract is used.
© 2019 DevartReference

975

Return Valuea new instance of the TMSConversation class.

Remarks
These overloaded methods initiate a dialog from one TMSServiceBroker.Service to anotherservice. A dialog is a conversation that provides messaging between two services.
Use BeginDialog to create an instance of the TMSConversation class. The new instance willbe created with the TMSConversation.IsInitiator property assigned to True.

See Also
TMSConversation
TMSConversation.EndConversation
TMSConversation.IsInitiator
TMSServiceBroker.Conversations
MSDN: BEGIN DIALOG CONVERSATION© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

Initiates a dialog from one TMSServiceBroker.Service to another service.

Class
TMSServiceBroker

Syntaxfunction BeginDialog(const TargetService: string; const
TargetDatabase: string; const UseEncryption: boolean; const
GroupId: TGuid; const LifeTime: integer = 0; const Contract:
string = ''): TMSConversation; overload;
Parameters
TargetService
The target service name that the conversation initiates with.
TargetDatabase
Specifies the database name that the target service hosts.
UseEncryption
Specifies whether messages within the conversation must be encrypted. When set to True(the default value), it may require applying additional server settings.
GroupId
Unique identifier of an existent group, which should join in the new conversation.
© 2019 Devart

976

SQL Server Data Access Components

LifeTime
Specifies the maximum time interval (in seconds) while the dialog remains open. After thisinterval expires, the dialog automatically closes. A zero LifeTime value represents an infinity
interval. This is the default value.
Contract
Specifies the name of the contract that the conversation conforms to. If the parameter is not
set, the DEFAULT contract is used.
Return Valuea new instance of the TMSConversation class.

See Also
TMSConversation
TMSConversation.EndConversation
TMSConversation.IsInitiator
TMSServiceBroker.Conversations
MSDN: BEGIN DIALOG CONVERSATION© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.2 CreateServerObjects Method

Creates a service and a queue on the server.

Class
TMSServiceBroker

Syntax
procedure CreateServerObjects(const Contract: string ='DEFAULT');
Parameters
Contract
Specifies the name of the contract that the conversation conforms to. If the parameter is not
set, the DEFAULT contract is used.

Remarks
If there are no such objects on the server, the service and the queue will be created on theserver. These objects are created with the default settings (any messages can be transferredin any direction). The queue name are generated by concatenating Service and the '_Queue'
prefix.
© 2019 DevartReference

977

See Also
DropServerObjects
ServiceQueue© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.3 DropServerObjects Method

Removes both the service with the name assigned to the Service property and the queue with
the name Service name + '_Queue'.

Class
TMSServiceBroker

Syntax
procedure DropServerObjects;

Remarks
This method removes both the service with the name assigned to the Service property andthe queue with the name Service name + '_Queue'.

See Also
CreateServerObjects
ServiceQueue© 1997-2019
Devart. All Rights
Reserved.

Request Support

5.20.1.3.3.4 GetContractNames Method

Delivers contract name from the server.

Class
TMSServiceBroker

Syntax© 2019 Devart

DAC Forum

Provide Feedback

978

SQL Server Data Access Components

procedure GetContractNames(List: TStrings);
Parameters
List
Holds the list of contract names.

Remarks
Call the GetContractNames method to get contract names from the server.

See Also
GetServiceNames
GetQueueNames
GetMessageTypeNames
TMSConversation.ContractName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.5 GetMessageTypeNames Method

Delivers the names of message types from the server.

Class
TMSServiceBroker

Syntax
procedure GetMessageTypeNames(List: TStrings);
Parameters
List
Holds the names of the message types.

Remarks
Call the GetMessageTypeNames method to get the names of message types from theserver.

See Also
GetServiceNames
GetContractNames
GetQueueNames© 2019 DevartReference

979

TMSConversation.Send© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.6 GetQueueNames Method

Delivers queue names from the server.

Class
TMSServiceBroker

Syntax
procedure GetQueueNames(List: TStrings);
Parameters
List
Holds the queue names.

Remarks
Call the GetQueueNames method to get queue names from the server.

See Also
GetServiceNames
GetContractNames
GetMessageTypeNames© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.20.1.3.3.7 GetServiceNames Method

Delivers queue names from the server.

Class
TMSServiceBroker

Syntax
procedure GetServiceNames(List: TStrings);
Parameters
List© 2019 Devart

Provide Feedback

980

SQL Server Data Access Components

Holds the service names.

Remarks
Call the GetServiceNames method to get service names from the server.

See Also
GetQueueNames
GetContractNames
GetMessageTypeNames
Service
TMSConversation.FarService© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.3.8 Receive Method

Designed for receiving messages from a queue on the server from the specified service.

Class
TMSServiceBroker

Syntaxfunction Receive(Conversation: TMSConversation = nil): boolean;
Parameters
Conversation
Holds the name of the conversation to recieve messages of.
Return Value
False, if there are no more messages on the server.

Remarks
The Receive method is designed for receiving messages from a queue on the server fromthe specified service. You can get access to the current message using the CurrentMessage
property.
If the Receive method returns False, there are no more messages on the server. So, theCurrentMessage will be nil.

The synchronous mode (AsyncNotification is False)
In this mode, after calling the Receive method, up to FetchRows messages are received from© 2019 DevartReference981

the server. The CurrentMessage property will point to the first message of the received ones.
The subsequent calls to Receive will not lead to the server round trips, while there aremessages in cache. This mode is enabled by default.
If the Conversation parameter is assigned, only messages of this conversation will bereceived.

The synchronous mode (AsyncNotification is True)
In this mode messages from the server are received in a separate thread and are put into a
local queue. Calls to Receive itself do not lead to the server round trips.
The Conversation parameter can not be used in the asynchronous mode.

ExampleExample for using Receive in synchronous mode:
while MSServiceBroker.Receive do
Process(MSServiceBroker.CurrentMessage);

See Also
Service
FetchRows
CurrentMessage
AsyncNotification
TMSMessage
TMSConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.4 Events

Events of the TMSServiceBroker class.
For a complete list of the TMSServiceBroker class members, see the TMSServiceBroker
Members topic.

Published
Name
OnBeginConversation© 2019 Devart

Description
Occurs when a new object of
the TMSConversation classis being created.

982

SQL Server Data Access Components

Occurs when an existing
conversation is being
closed.
Occurs when a newmessage is received in theasynchronous mode.

OnEndConversation

OnMessage

See Also
TMSServiceBroker Class
TMSServiceBroker Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.4.1 OnBeginConversation Event

Occurs when a new object of the TMSConversation class is being created.

Class
TMSServiceBroker

Syntaxproperty OnBeginConversation: TMSConversationBeginEvent;Remarks
The OnBeginConversation event occurs when creating a new object of the TMSConversation
class.

See Also
TMSConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.4.2 OnEndConversation Event

Occurs when an existing conversation is being closed.

Class
TMSServiceBroker© 2019 DevartReference

983

Syntaxproperty OnEndConversation: TMSConversationEndEvent;Remarks
The OnEndConversation event occurs when closing an existent conversation. The
conversation can be closed due to the following reasons:
The TMSConversation.EndConversation method is called.
A message with the SEndDialogType or SErrorType message type is received.

See Also
TMSConversation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.1.3.4.3 OnMessage Event

Occurs when a new message is received in the asynchronous mode.

Class
TMSServiceBroker

Syntaxproperty OnMessage: TMSMessageEvent;Remarks
The OnMessage event occurs when a new message is received in the asynchronous mode
(AsyncNotification is set to True).
This event is called in the context of the main thread.

Exampleprocedure TForm1.MSServiceBrokerMessage(Sender: TObject);
begin
while MSServiceBroker.Receive do
Process(MSServiceBroker.CurrentMessage);end;

See Also
AsyncNotification© 2019 Devart

984

SQL Server Data Access Components

Receive© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.2 Enumerations
Enumerations in the MSServiceBroker unit.

Enumerations
Name

Description
Defines the type ofvalidation performed.

TMSMessageValidation© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.20.2.1 TMSMessageValidation Enumeration

Defines the type of validation performed.

Unit
MSServiceBroker

SyntaxTMSMessageValidation = (mvEmpty, mvNone, mvXML);

ValuesValue
mvEmpty
mvNonemvXML© 1997-2019
Devart. All Rights
Reserved.

5.21

Meaning
The message should be empty.
Validation is not performed.
The message should be a well-formed XML document.
Request Support

DAC Forum

Provide Feedback

MSSQLMonitor
This unit contains implementation of the TMSSQLMonitor component.

Classes© 2019 DevartReference

Name

Description
This component serves formonitoring dynamic SQL
execution in SDAC-based
applications.

TMSSQLMonitor© 1997-2019
Devart. All Rights
Reserved.

985

Request Support

DAC Forum

Provide Feedback

5.21.1 Classes
Classes in the MSSQLMonitor unit.

ClassesName

Description
This component serves formonitoring dynamic SQL
execution in SDAC-based
applications.

TMSSQLMonitor© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.21.1.1 TMSSQLMonitor ClassThis component serves for monitoring dynamic SQL execution in SDAC-based applications.
For a list of all members of this type, see TMSSQLMonitor members.

Unit
MSSQLMonitor

SyntaxTMSSQLMonitor = class(TCustomDASQLMonitor);

Remarks
Use TMSSQLMonitor to monitor dynamic SQL execution in SDAC-based applications.
TMSSQLMonitor provides two ways of displaying debug information: with dialog window,
DBMonitor or Borland SQL Monitor. Furthermore to receive debug information the
TCustomDASQLMonitor.OnSQL event can be used. Also it is possible to use all these ways
at the same time, though an application may have only one TMSSQLMonitor object. If an© 2019 Devart

986

SQL Server Data Access Components

application has no TMSSQLMonitor instance, the Debug window is available to display SQL
statements to be sent.

Inheritance Hierarchy
TCustomDASQLMonitor
TMSSQLMonitor

See Also
TCustomDADataSet.Debug
TCustomDASQL.Debug
DBMonitor© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.21.1.1.1 Members

TMSSQLMonitor class overview.

Properties
Name
Active (inherited from TCustomDASQLMonitor)
DBMonitorOptions (inherited from

Description
Used to activate monitoringof SQL.
Used to set options for
dbMonitor.

TCustomDASQLMonitor)
Options (inherited from TCustomDASQLMonitor)

TraceFlags (inherited from TCustomDASQLMonitor)

Used to include the desired
properties for
TCustomDASQLMonitor.
Used to specify which
database operations themonitor should track in an
application at runtime.

EventsName
OnSQL (inherited from TCustomDASQLMonitor)© 1997-2019

Request Support

DAC Forum

Description
Occurs when tracing of SQL
activity on database
components is needed.
Provide Feedback© 2019 DevartReference

987

Devart. All Rights
Reserved.

5.22

MSTransaction
This unit contains implementation of the TMSTransaction component.

ClassesName

Description
A component for managing
transactions in an
application.

TMSTransaction© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1 Classes
Classes in the MSTransaction unit.

ClassesName

Description
A component for managing
transactions in an
application.

TMSTransaction© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

5.22.1.1 TMSTransaction Class

A component for managing transactions in an application.
For a list of all members of this type, see TMSTransaction members.

Unit
MSTransaction

SyntaxTMSTransaction = class(TCustomMSTransaction);

Remarks© 2019 Devart

Provide Feedback

988

SQL Server Data Access Components

The TMSTransaction component is used to provide discrete transaction control overconnection. It can be used for manipulating simple local and global transactions. It is basedon the Microsoft Distributed Transaction Coordinator functionality.
You can add connections in TMSTransaction both before calling the StartTransaction method,
and after that. It means that a transaction can be started before a connection is added.
Connections can be added and removed later, when a transaction is active. A transaction is
distributed regardless of connection count in it.

Inheritance Hierarchy
TDATransaction
TCustomMSTransaction
TMSTransaction

See Also
TMSTransaction Component© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1.1.1 Members

TMSTransaction class overview.

Properties
Name
ConnectionsCount

IsolationLevel

Description
Used to get the number ofconnections associated withthe transaction component.
Used to specify how thetransactions containing
database modifications arehandled.

Methods
Name
AddConnection

Description
Binds aTCustomDAConnection
object with the transaction
component.

© 2019 DevartReference

Disassociates the specified
connections from atransaction.

RemoveConnection© 1997-2019
Devart. All Rights
Reserved.

989

Request Support

DAC Forum

Provide Feedback

5.22.1.1.2 Properties

Properties of the TMSTransaction class.
For a complete list of the TMSTransaction class members, see the TMSTransaction
Members topic.

PublicName

Description
Used to get the number ofconnections associated withthe transaction component.

ConnectionsCount

Published
Name

Description
Used to specify how thetransactions containing
database modifications arehandled.

IsolationLevel

See Also
TMSTransaction Class
TMSTransaction Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1.1.2.1 ConnectionsCount Property

Used to get the number of connections associated with the transaction component.

Class
TMSTransaction© 2019 Devart

990

SQL Server Data Access Components

Syntaxproperty ConnectionsCount: integer;

Remarks
Use the ConnectionsCount property for getting the number of connections associated withthe transaction component.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1.1.2.2 IsolationLevel Property

Used to specify how the transactions containing database modifications are handled.

Class
TMSTransaction

Syntaxproperty IsolationLevel: TIsolationLevel default ilReadCommitted;

Remarks
Use the IsolationLevel property to specify how the transactions containing databasemodifications are handled.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1.1.3 Methods

Methods of the TMSTransaction class.
For a complete list of the TMSTransaction class members, see the TMSTransaction
Members topic.

PublicName
AddConnection

Description
Binds aTCustomDAConnection
object with the transaction
component.

© 2019 DevartReference

991

Disassociates the specified
connections from atransaction.

RemoveConnection

See Also
TMSTransaction Class
TMSTransaction Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.22.1.1.3.1 AddConnection Method

Binds a TCustomDAConnection object with the transaction component.

Class
TMSTransaction

Syntaxfunction AddConnection(Connection: TCustomDAConnection): integer;
Parameters
Connection
Holds a TCustomDAConnection object to associate with the transaction component.
Return Valuethe index of associated connection in the connection list.

Remarks
Use the AddConnection method to associate a TCustomDAConnection object with thetransaction component.

See Also
RemoveConnection© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

992

SQL Server Data Access Components

5.22.1.1.3.2 RemoveConnection Method

Disassociates the specified connections from a transaction.

Class
TMSTransaction

Syntax
procedure RemoveConnection(Connection: TCustomDAConnection);
Parameters
Connection
Holds the connections to disassociate.

Remarks
Use the RemoveConnection method to disassociate the specified connections from atransaction.

See Also
AddConnection© 1997-2019
Devart. All Rights
Reserved.

5.23

Request Support

DAC Forum

Provide Feedback

OLEDBAccessThis unit contains classes for accessing SQL Server through OLE DB providers

ClassesName
EMSError
EOLEDBError

Description
Raised when SQL Server
returns error as a result.
Raised when a component
receives an OLE DB error.

Variables
Name
ParamsInfoOldBehavior

Description
Preparing and the first call ofa stored procedure are
combined for performance© 2019 DevartReference993

optimization.
© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1 Classes
Classes in the OLEDBAccess unit.

ClassesName

Description
Raised when SQL Server
returns error as a result.
Raised when a component
receives an OLE DB error.

EMSError
EOLEDBError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1 EMSError Class

Raised when SQL Server returns error as a result.
For a list of all members of this type, see EMSError members.

Unit
OLEDBAccess

SyntaxEMSError = class(EOLEDBError);

Remarks
EMSError is raised when SQL Server returns error as a result, for example, of an attempt to
execute invalid SQL statement. Use EMSError in the exception-handling block.

Inheritance Hierarchy
EDAError
EOLEDBError
EMSErrorSee Also© 2019 Devart

994

SQL Server Data Access Components

EOLEDBError
EDAError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.1 Members

EMSError class overview.

Properties
Name
Component (inherited from EDAError)
ErrorCode (inherited from EDAError)
ErrorCount (inherited from EOLEDBError)
Errors (inherited from EOLEDBError)
LastMessage
LineNumber

MessageWide (inherited from EOLEDBError)
MSSQLErrorCode
OLEDBErrorCode (inherited from EOLEDBError)
ProcName

ServerName
SeverityClass
State© 1997-2019

Request Support

DAC Forum

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.
Contains the number of
errors returned by the server.
Contains an array of errors
returned by the server.
Contains SQL Server lasterror message.
Contains the line number ofa stored procedure on which
the error occurred.
Used to represent theUnicode equivalent of
Exception.
Contains the code of a SQL
Server error.
Contains the code of OLE
DB Error.
Contains the name of thestored procedure thatgenerated the error.
Contains the name of theserver that generated theerror.
Contains severity of a SQL
Server message.
Contains the state of a SQL
Server error message.
Provide Feedback© 2019 DevartReference

995

Devart. All Rights
Reserved.
5.23.1.1.2 Properties

Properties of the EMSError class.
For a complete list of the EMSError class members, see the EMSError Members topic.

PublicName
Component (inherited from EDAError)
ErrorCode (inherited from EDAError)
ErrorCount (inherited from EOLEDBError)
Errors (inherited from EOLEDBError)
LastMessage
LineNumber

MessageWide (inherited from EOLEDBError)
MSSQLErrorCode
OLEDBErrorCode (inherited from EOLEDBError)
ProcName

ServerName
SeverityClassState

See Also
EMSError Class© 2019 Devart

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.
Contains the number of
errors returned by the server.
Contains an array of errors
returned by the server.
Contains SQL Server lasterror message.
Contains the line number ofa stored procedure on which
the error occurred.
Used to represent theUnicode equivalent of
Exception.
Contains the code of a SQL
Server error.
Contains the code of OLE
DB Error.
Contains the name of thestored procedure thatgenerated the error.
Contains the name of theserver that generated theerror.
Contains severity of a SQL
Server message.
Contains the state of a SQL
Server error message.

996

SQL Server Data Access Components

EMSError Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.2.1 LastMessage Property

Contains SQL Server last error message.

Class
EMSError

Syntaxproperty LastMessage: string;

Remarks
LastMessage contains SQL Server last error message.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.2.2 LineNumber Property

Contains the line number of a stored procedure on which the error occurred.

Class
EMSError

Syntaxproperty LineNumber: WORD;

Remarks
When applicable, the LineNumber property contains the line number of a stored procedure on
which the error occurred.

See Also
ProcName© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference997

5.23.1.1.2.3 MSSQLErrorCode Property

Contains the code of a SQL Server error.

Class
EMSError

Syntaxproperty MSSQLErrorCode: integer;

Remarks
Code of the SQL Server error. Refer to MSDN for detail description of errors code. Using
MSSQLErrorCode is more preferable than using ErrorCode, as decoding the last one
depends on the class of an error (EOLEDBError or EMSError).

See Also
EMSError
EDAError.ErrorCode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.2.4 ProcName Property

Contains the name of the stored procedure that generated the error.

Class
EMSError

Syntaxproperty ProcName: string;

Remarks
The ProcName property contains the name of the stored procedure that generated the error.
This property may be empty if no stored procedure was called.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

998

SQL Server Data Access Components

5.23.1.1.2.5 ServerName Property

Contains the name of the server that generated the error.

Class
EMSError

Syntaxproperty ServerName: string;

Remarks
The ServerName property contains the name of the server that generated the error.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.2.6 SeverityClass Property

Contains severity of a SQL Server message.

Class
EMSError

Syntaxproperty SeverityClass: BYTE;

Remarks
The SeverityClass property contains severity of a SQL Server message.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.1.2.7 State Property

Contains the state of a SQL Server error message.

Class
EMSError

Syntaxproperty State: BYTE;© 2019 DevartReference

999

Remarks
The State property contains the state of a SQL Server error message. See the SQL Server
documentation for more details.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2 EOLEDBError Class

Raised when a component receives an OLE DB error.
For a list of all members of this type, see EOLEDBError members.

Unit
OLEDBAccess

SyntaxEOLEDBError = class(EDAError);

Remarks
EOLEDBError is raised when a component receives an OLE DB error. Use EOLEDBError in
the exception-handling block.
If several errors happen during execution of the same SQL statement, all these errors are
stored into the Errors property. For example, if the following query will be executed:'SELECT WrongField1, WrongField2 FROM Northwind..Orders'ErrorCount equals to 2 and the Errors property contains two errors ('Invalid column name'WrongField1'.' and 'Invalid column name 'WrongField2'.').
Keep in mind, if MSConnection.Connect was called from another thread than this event, thetext of the message can be incomplete.

Inheritance Hierarchy
EDAError
EOLEDBError

See Also
EMSError
EDAError© 1997-2019
Devart. All Rights© 2019 Devart

Request Support

DAC Forum

Provide Feedback

1000

SQL Server Data Access Components

Reserved.
5.23.1.2.1 Members

EOLEDBError class overview.

Properties
Name

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.
Contains the number of
errors returned by the server.
Contains an array of errors
returned by the server.
Used to represent theUnicode equivalent of
Exception.
Contains the code of OLE
DB Error.

Component (inherited from EDAError)
ErrorCode (inherited from EDAError)
ErrorCount
ErrorsMessageWide
OLEDBErrorCode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2.2 Properties

Properties of the EOLEDBError class.
For a complete list of the EOLEDBError class members, see the EOLEDBError Members
topic.

PublicName
Component (inherited from EDAError)
ErrorCode (inherited from EDAError)
ErrorCount
ErrorsMessageWide

Description
Contains the component thatcaused the error.
Determines the error code
returned by the server.
Contains the number of
errors returned by the server.
Contains an array of errors
returned by the server.
Used to represent the© 2019 DevartReference

1001

Unicode equivalent of
Exception.
Contains the code of OLE
DB Error.

OLEDBErrorCode

See Also
EOLEDBError ClassEOLEDBError Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2.2.1 ErrorCount Property

Contains the number of errors returned by the server.

Class
EOLEDBError

Syntaxproperty ErrorCount: integer;

Remarks
The number of errors returned by the server.

See Also
EMSError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2.2.2 Errors Property(Indexer)

Contains an array of errors returned by the server.

Class
EOLEDBError

Syntaxproperty Errors[Index: Integer]: EOLEDBError; default;© 2019 Devart

1002

SQL Server Data Access Components

Parameters
Index
Holds the number of the error to access.

Remarks
The Errors property contains the array of errors returned by the server.

See Also
EOLEDBError
EMSError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2.2.3 MessageWide Property

Used to represent the Unicode equivalent of Exception.

Class
EOLEDBError

Syntaxproperty MessageWide: string;

Remarks
This property represents the Unicode equivalent of Exception.Message. Useful for the client
applications working on systems that have charset incompatible with the server charset.

See Also
EMSError© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.1.2.2.4 OLEDBErrorCode Property

Contains the code of OLE DB Error.

Class
EOLEDBError© 2019 DevartReference

1003

Syntaxproperty OLEDBErrorCode: integer;

Remarks
The OLEDBErrorCode holds the code of OLE DB Error. Refer to MSDN for the detailed
description of the error code. Using OLEDBErrorCode is more preferable than using
ErrorCode, as decoding the last one depends on the class of an error (EOLEDBError or
EMSError).

See Also
EMSError
EDAError.ErrorCode© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.2 Variables
Variables in the OLEDBAccess unit.

Variables
Name

Description
Preparing and the first call ofa stored procedure are
combined for performance
optimization.

ParamsInfoOldBehavior© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.23.2.1 ParamsInfoOldBehavior Variable

Preparing and the first call of a stored procedure are combined for performance optimization.

Unit
OLEDBAccess

SyntaxParamsInfoOldBehavior: boolean;© 2019 Devart

1004

SQL Server Data Access Components

Remarks
Starting with SDAC 3.70.1.26 preparing and the first call of a stored procedure werecombined for performance optimization. This requires the necessity of setting the parameter
type and data type of all parameters before preparing. In order to revert the old behaviour withpreparation and parameters, the OLEDBAccess unit should be added to the uses clause of aunit in an application, and the following line should be added to the initialization section of theunit:
ParamsInfoOldBehavior := True.

© 1997-2019
Devart. All Rights
Reserved.

5.24

Request Support

DAC Forum

Provide Feedback

SdacVclThis unit contains the visual constituent of SDAC.

ClassesName

Description
A class that provides a
dialog box for user to supply
his login information.

TMSConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.24.1 Classes
Classes in the SdacVcl unit.

ClassesName

Description
A class that provides a
dialog box for user to supply
his login information.

TMSConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

1005

5.24.1.1 TMSConnectDialog ClassA class that provides a dialog box for user to supply his login information.
For a list of all members of this type, see TMSConnectDialog members.

Unit
SdacVclSyntaxTMSConnectDialog = class(TCustomConnectDialog);

Remarks
The TMSConnectDialog component is a direct descendant of TCustomConnectDialog class.
Use TMSConnectDialog to provide dialog box for user to supply server name, user name, andpassword. You may want to customize appearance of dialog box using this class's
properties.

Inheritance Hierarchy
TCustomConnectDialog
TMSConnectDialog

See Also
TCustomDAConnection.ConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.24.1.1.1 Members

TMSConnectDialog class overview.

Properties
Name

Description
CancelButton (inherited from TCustomConnectDialog) Used to specify the label for
the Cancel button.
Used to set the caption of
Caption (inherited from TCustomConnectDialog)
dialog box.
ConnectButton (inherited from TCustomConnectDialog) Used to specify the label for
the Connect button.
Connection
Contains the© 2019 Devart

1006

SQL Server Data Access Components

DialogClass (inherited from TCustomConnectDialog)

LabelSet (inherited from TCustomConnectDialog)
PasswordLabel (inherited fromTCustomMSConnection thatis used by
TMSConnectDialog object.
Used to specify the class ofthe form that will be
displayed to enter login
information.
Used to set the language ofbuttons and labels captions.
Used to specify a prompt for
password edit.

TCustomConnectDialog)
Retries (inherited from TCustomConnectDialog)
SavePassword (inherited fromTCustomConnectDialog)
ServerLabel (inherited from TCustomConnectDialog)

StoreLogInfo (inherited from TCustomConnectDialog)

UsernameLabel (inherited from

Used to indicate the numberof retries of failed
connections.
Used for the password to be
displayed in ConnectDialog
in asterisks.
Used to specify a prompt forthe server name edit.
Used to specify whether thelogin information should be
kept in system registry after
a connection wasestablished.
Used to specify a prompt forusername edit.

TCustomConnectDialog)

Methods
Name
Execute (inherited from TCustomConnectDialog)

GetServerList© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Displays the connect dialog
and calls the connection's
Connect method when user
clicks the Connect button.
Retrieves the list of available
database servers.
Provide Feedback© 2019 DevartReference

1007

5.24.1.1.2 Properties

Properties of the TMSConnectDialog class.
For a complete list of the TMSConnectDialog class members, see the TMSConnectDialog
Members topic.

PublicName

Description
CancelButton (inherited from TCustomConnectDialog) Used to specify the label for
the Cancel button.
Used to set the caption of
Caption (inherited from TCustomConnectDialog)
dialog box.
ConnectButton (inherited from TCustomConnectDialog) Used to specify the label for
the Connect button.
Contains theTCustomMSConnection that
Connection
is used by
TMSConnectDialog object.
Used to specify the class of
DialogClass (inherited from TCustomConnectDialog) the form that will be
displayed to enter login
information.
Used to set the language ofLabelSet (inherited from TCustomConnectDialog)
buttons and labels captions.
PasswordLabel (inherited from
Used to specify a prompt for
TCustomConnectDialog)
Retries (inherited from TCustomConnectDialog)
SavePassword (inherited fromTCustomConnectDialog)
ServerLabel (inherited from TCustomConnectDialog)

StoreLogInfo (inherited from TCustomConnectDialog)

UsernameLabel (inherited fromTCustomConnectDialog)© 2019 Devart

password edit.
Used to indicate the numberof retries of failed
connections.
Used for the password to be
displayed in ConnectDialog
in asterisks.
Used to specify a prompt forthe server name edit.
Used to specify whether thelogin information should be
kept in system registry after
a connection wasestablished.
Used to specify a prompt forusername edit.

1008

SQL Server Data Access Components

See Also
TMSConnectDialog ClassTMSConnectDialog Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.24.1.1.2.1 Connection Property

Contains the TCustomMSConnection that is used by TMSConnectDialog object.

Class
TMSConnectDialog

Syntaxproperty Connection: TCustomMSConnection;

Remarks
Read Connection property to find out what TCustomMSConnection uses the
TMSConnectDialog object. This property is read-only.

See Also
TCustomDAConnection.ConnectDialog© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.24.1.1.3 Methods

Methods of the TMSConnectDialog class.
For a complete list of the TMSConnectDialog class members, see the TMSConnectDialog
Members topic.

PublicName
Execute (inherited from TCustomConnectDialog)

Description
Displays the connect dialog
and calls the connection's
Connect method when user
clicks the Connect button.

© 2019 DevartReference

1009

Retrieves the list of available
database servers.

GetServerList

See Also
TMSConnectDialog ClassTMSConnectDialog Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.24.1.1.3.1 GetServerList Method

Retrieves the list of available database servers.

Class
TMSConnectDialog

Syntax
procedure GetServerList(List: TStrings); override;
Parameters
List
A TStrings descendant that will be filled with database servers names.

Remarks
Call GetServerList method to retrieve the list of available database servers. It is useful for
writing custom login forms.

© 1997-2019
Devart. All Rights
Reserved.

5.25

Request Support

DAC Forum

Provide Feedback

VirtualDataSet
This unit contains implementation of the TVirtualDataSet component.

ClassesName
TCustomVirtualDataSet© 2019 Devart

Description
A base class forrepresentation of arbitrary
data in tabular form.

1010

SQL Server Data Access Components

Dataset that processes
arbitrary non-tabular data.

TVirtualDataSet

Types
Name

Description
This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnDeleteRecord event.
This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnGetFieldValue event.
This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnGetRecordCount
event.
This type is used for
E:Devart.Dac.TVirtualDataS
et.OnInsertRecord andE:Devart.Dac.TVirtualDataS
et.OnModifyRecord events.

TOnDeleteRecordEvent

TOnGetFieldValueEvent

TOnGetRecordCountEvent

TOnModifyRecordEvent© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.1 Classes
Classes in the VirtualDataSet unit.

ClassesName

Description
A base class forrepresentation of arbitrary
data in tabular form.
Dataset that processes
arbitrary non-tabular data.

TCustomVirtualDataSet
TVirtualDataSet© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 DevartReference

1011

5.25.1.1 TCustomVirtualDataSet ClassA base class for representation of arbitrary data in tabular form.
For a list of all members of this type, see TCustomVirtualDataSet members.

Unit
VirtualDataSet

SyntaxTCustomVirtualDataSet = class(TMemDataSet);

Inheritance Hierarchy
TMemDataSet
TCustomVirtualDataSet© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.1.1.1 Members

TCustomVirtualDataSet class overview.

Properties
Name
CachedUpdates (inherited from TMemDataSet)

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)
Prepared (inherited from TMemDataSet)© 2019 Devart

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a query1012

SQL Server Data Access Components

Ranged (inherited from TMemDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

is prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

Locate (inherited from TMemDataSet)

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Overloaded. Searches adataset for a specific recordand positions the cursor on© 2019 DevartReference

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)© 2019 Devart

1013

it.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset when

1014

SQL Server Data Access Components

cached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.

DAC Forum

Provide Feedback

5.25.1.2 TVirtualDataSet Class

Dataset that processes arbitrary non-tabular data.
For a list of all members of this type, see TVirtualDataSet members.

Unit
VirtualDataSet

SyntaxTVirtualDataSet = class(TCustomVirtualDataSet);

Inheritance Hierarchy
TMemDataSet
TCustomVirtualDataSet
TVirtualDataSet© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.1.2.1 Members

TVirtualDataSet class overview.

Properties© 2019 DevartReference

Name
CachedUpdates (inherited from TMemDataSet)

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

1015

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

CancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)© 2019 Devart

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its prior

1016

SQL Server Data Access Components

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)
SetRangeEnd (inherited from TMemDataSet)

state.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.
Indicates that subsequent© 2019 DevartReference

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

1017

assignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.25.2 Types
Types in the VirtualDataSet unit.

Types
Name
© 2019 Devart

Description

1018

SQL Server Data Access Components

This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnDeleteRecord event.
This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnGetFieldValue event.
This type is used for the
E:Devart.Dac.TVirtualDataS
et.OnGetRecordCount
event.
This type is used for
E:Devart.Dac.TVirtualDataS
et.OnInsertRecord andE:Devart.Dac.TVirtualDataS
et.OnModifyRecord events.

TOnDeleteRecordEvent

TOnGetFieldValueEvent

TOnGetRecordCountEvent

TOnModifyRecordEvent© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.2.1 TOnDeleteRecordEvent Procedure ReferenceThis type is used for the E:Devart.Dac.TVirtualDataSet.OnDeleteRecord event.

Unit
VirtualDataSet

SyntaxTOnDeleteRecordEvent = procedure (Sender: TObject; RecNo:
Integer) of object;Parameters
SenderAn object that raised the event.
RecNo
Number of the record being deleted.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.2.2 TOnGetFieldValueEvent Procedure ReferenceThis type is used for the E:Devart.Dac.TVirtualDataSet.OnGetFieldValue event.

Unit© 2019 DevartReference

1019

VirtualDataSet

SyntaxTOnGetFieldValueEvent = procedure (Sender: TObject; Field: TField;
RecNo: Integer; out Value: Variant) of object;Parameters
SenderAn object that raised the event.
Field
The field, which data has to be returned.
RecNo
The number of the record, which data has to be returned.
Value
Requested field value.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.25.2.3 TOnGetRecordCountEvent Procedure ReferenceThis type is used for the E:Devart.Dac.TVirtualDataSet.OnGetRecordCount event.

Unit
VirtualDataSet

SyntaxTOnGetRecordCountEvent = procedure (Sender: TObject; out Count:Integer) of object;Parameters
SenderAn object that raised the event.
Count
The number of records that the virtual dataset will contain.

© 1997-2019
Devart. All Rights
Reserved.

© 2019 Devart

Request Support

DAC Forum

Provide Feedback

1020

SQL Server Data Access Components

5.25.2.4 TOnModifyRecordEvent Procedure ReferenceThis type is used for E:Devart.Dac.TVirtualDataSet.OnInsertRecord andE:Devart.Dac.TVirtualDataSet.OnModifyRecord events.

Unit
VirtualDataSet

SyntaxTOnModifyRecordEvent = procedure (Sender: TObject; var RecNo:
Integer) of object;Parameters
SenderAn object that raised the event.
RecNo
Number of the record being inserted or modified.

© 1997-2019
Devart. All Rights
Reserved.

5.26

Request Support

DAC Forum

Provide Feedback

VirtualTable
This unit contains implementation of the TVirtualTable component.

ClassesName

Description
Dataset that stores data inmemory. This component isplaced on the Data Accesspage of the Component
palette.

TVirtualTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1 Classes
Classes in the VirtualTable unit.

Classes© 2019 DevartReference

Name

Description
Dataset that stores data inmemory. This component isplaced on the Data Accesspage of the Component
palette.

TVirtualTable© 1997-2019
Devart. All Rights
Reserved.

1021

Request Support

DAC Forum

Provide Feedback

5.26.1.1 TVirtualTable Class

Dataset that stores data in memory. This component is placed on the Data Access page of
the Component palette.
For a list of all members of this type, see TVirtualTable members.

Unit
VirtualTable

SyntaxTVirtualTable = class(TMemDataSet);

Inheritance Hierarchy
TMemDataSet
TVirtualTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1.1.1 Members

TVirtualTable class overview.

Properties
Name
CachedUpdates (inherited from TMemDataSet)

DefaultSortType© 2019 Devart

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to determine thedefault type of local sortingfor string fields.

1022

SQL Server Data Access Components

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Methods
Name
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

AssignCancelRange (inherited from TMemDataSet)

CancelUpdates (inherited from TMemDataSet)

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Copies fields and data fromanother TDataSet
component.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache andrestores dataset in its priorstate.
© 2019 DevartReference

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

LoadFromFile
Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)© 2019 Devart

1023

Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Loads data from file into a
TVirtualTable component.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending
values of a range, andapplies it.

1024

SQL Server Data Access Components

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

EventsName
OnUpdateError (inherited from TMemDataSet)

OnUpdateRecord (inherited from TMemDataSet)© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Description
Occurs when an exception is
generated while cachedupdates are applied to a
database.
Occurs when a single
update component can nothandle the updates.
Provide Feedback

5.26.1.1.2 Properties

Properties of the TVirtualTable class.
For a complete list of the TVirtualTable class members, see the TVirtualTable Members
topic.

© 2019 DevartReference

1025

PublicName
CachedUpdates (inherited from TMemDataSet)

IndexFieldNames (inherited from TMemDataSet)

KeyExclusive (inherited from TMemDataSet)

LocalConstraints (inherited from TMemDataSet)

LocalUpdate (inherited from TMemDataSet)

Prepared (inherited from TMemDataSet)
Ranged (inherited from TMemDataSet)

UpdateRecordTypes (inherited from TMemDataSet)

UpdatesPending (inherited from TMemDataSet)

Description
Used to enable or disable
the use of cached updates
for a dataset.
Used to get or set the list offields on which the recordset
is sorted.
Specifies the upper andlower boundaries for arange.
Used to avoid setting theRequired property of a
TField component for NOT
NULL fields at the time of
opening TMemDataSet.
Used to prevent implicit
update of rows on databaseserver.
Determines whether a queryis prepared for execution ornot.
Indicates whether a range isapplied to a dataset.
Used to indicate the update
status for the current record
when cached updates areenabled.
Used to check the status of
the cached updates buffer.

Published
Name
DefaultSortType

See Also
TVirtualTable Class
TVirtualTable Class Members© 2019 Devart

Description
Used to determine thedefault type of local sortingfor string fields.

1026

SQL Server Data Access Components© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1.1.2.1 DefaultSortType Property

Used to determine the default type of local sorting for string fields.

Class
TVirtualTable

Syntaxproperty DefaultSortType: TSortType default stCaseSensitive;

Remarks
The DefaultSortType property is used when a sort type is not specified explicitly after the fieldname in the TMemDataSet.IndexFieldNames property of a dataset.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1.1.3 Methods

Methods of the TVirtualTable class.
For a complete list of the TVirtualTable class members, see the TVirtualTable Members
topic.

PublicName
ApplyRange (inherited from TMemDataSet)
ApplyUpdates (inherited from TMemDataSet)

AssignCancelRange (inherited from TMemDataSet)
CancelUpdates (inherited from TMemDataSet)

Description
Applies a range to thedataset.
Overloaded. Writes
dataset's pending cachedupdates to a database.
Copies fields and data fromanother TDataSet
component.
Removes any ranges
currently in effect for adataset.
Clears all pending cachedupdates from cache and© 2019 DevartReference

CommitUpdates (inherited from TMemDataSet)
DeferredPost (inherited from TMemDataSet)
EditRangeEnd (inherited from TMemDataSet)

EditRangeStart (inherited from TMemDataSet)

GetBlob (inherited from TMemDataSet)

LoadFromFile
Locate (inherited from TMemDataSet)

LocateEx (inherited from TMemDataSet)

Prepare (inherited from TMemDataSet)

RestoreUpdates (inherited from TMemDataSet)

RevertRecord (inherited from TMemDataSet)

SaveToXML (inherited from TMemDataSet)

SetRange (inherited from TMemDataSet)© 2019 Devart

1027

restores dataset in its priorstate.
Clears the cached updates
buffer.
Makes permanent changes
to the database server.
Enables changing theending value for an existing
range.
Enables changing thestarting value for an existing
range.
Overloaded. Retrieves
TBlob object for a field or
current record when only its
name or the field itself isknown.
Loads data from file into a
TVirtualTable component.
Overloaded. Searches adataset for a specific recordand positions the cursor onit.
Overloaded. Excludes
features that don't need to
be included to the
TMemDataSet.Locate
method of TDataSet.
Allocates resources andcreates field components fora dataset.
Marks all records in thecache of updates asunapplied.
Cancels changes made to
the current record whencached updates areenabled.
Overloaded. Saves thecurrent dataset data to a fileor a stream in the XML
format compatible with ADO
format.
Sets the starting and ending

1028

SQL Server Data Access Components

SetRangeEnd (inherited from TMemDataSet)

SetRangeStart (inherited from TMemDataSet)

UnPrepare (inherited from TMemDataSet)

UpdateResult (inherited from TMemDataSet)

UpdateStatus (inherited from TMemDataSet)

values of a range, andapplies it.
Indicates that subsequentassignments to field values
specify the end of the rangeof rows to include in thedataset.
Indicates that subsequentassignments to field values
specify the start of the rangeof rows to include in thedataset.
Frees the resources
allocated for a previously
prepared query on theserver and client sides.
Reads the status of thelatest call to the
ApplyUpdates method whilecached updates areenabled.
Indicates the current update
status for the dataset whencached updates areenabled.

See Also
TVirtualTable Class
TVirtualTable Class Members© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1.1.3.1 Assign Method

Copies fields and data from another TDataSet component.

Class
TVirtualTable

Syntax
procedure Assign(Source: TPersistent); override;© 2019 DevartReference

1029

Parameters
SourceHolds the TDataSet component to copy fields and data from.

Remarks
Call the Assign method to copy fields and data from another TDataSet component.
Note: Unsupported field types are skipped (i.e. destination dataset will contain less fields than
the source one). This may happen when Source is not a TVirtualTable component but someserver-oriented dataset.

ExampleQuery1.SQL.Text := 'SELECT * FROM DEPT';
Query1.Active := True;
VirtualTable1.Assign(Query1);
VirtualTable1.Active := True;
MSQuery1.SQL.Text := 'SELECT * FROM Orders';
MSQuery1.Active := True;
VirtualTable1.Assign(MSQuery1);
VirtualTable1.Active := True;

See Also
TVirtualTable© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback

5.26.1.1.3.2 LoadFromFile Method

Loads data from file into a TVirtualTable component.

Class
TVirtualTable

Syntax
procedure LoadFromFile(const FileName: string; LoadFields:
boolean = True; DecodeHTMLEntities: boolean = True);
Parameters
FileName
Holds the name of the file to load data from.
LoadFields
Indicates whether to load fields from the file.
© 2019 Devart

1030

SQL Server Data Access Components

DecodeHTMLEntities

Remarks
Call the LoadFromFile method to load data from file into a TVirtualTable component. Specify
the name of the file to load into the field as the value of the FileName parameter.This file may
be an XML document in ADO-compatible format or in virtual table data format. File format will
be detected automatically.

© 1997-2019
Devart. All Rights
Reserved.

Request Support

DAC Forum

Provide Feedback© 2019 Devart