fireruby 0.4.1-mswin32 → 0.4.2-mswin32

Sign up to get free protection for your applications and to get access to all the features.
Files changed (75) hide show
  1. data/doc/README +456 -456
  2. data/doc/license.txt +411 -411
  3. data/examples/example01.rb +65 -65
  4. data/lib/SQLType.rb +223 -227
  5. data/lib/fireruby.rb +22 -22
  6. data/lib/fr_lib.so +0 -0
  7. data/lib/mkdoc +1 -1
  8. data/lib/src.rb +1795 -1795
  9. data/test/AddRemoveUserTest.rb +56 -55
  10. data/test/BackupRestoreTest.rb +99 -99
  11. data/test/BlobTest.rb +57 -0
  12. data/test/CharacterSetTest.rb +63 -63
  13. data/test/ConnectionTest.rb +111 -111
  14. data/test/DDLTest.rb +54 -54
  15. data/test/DatabaseTest.rb +83 -83
  16. data/test/GeneratorTest.rb +50 -50
  17. data/test/KeyTest.rb +140 -140
  18. data/test/ResultSetTest.rb +162 -162
  19. data/test/RoleTest.rb +73 -0
  20. data/test/RowCountTest.rb +65 -65
  21. data/test/RowTest.rb +203 -203
  22. data/test/SQLTest.rb +182 -182
  23. data/test/SQLTypeTest.rb +101 -101
  24. data/test/ServiceManagerTest.rb +29 -29
  25. data/test/StatementTest.rb +135 -135
  26. data/test/TestSetup.rb +11 -11
  27. data/test/TransactionTest.rb +112 -112
  28. data/test/TypeTest.rb +92 -92
  29. data/test/UnitTest.rb +65 -64
  30. metadata +49 -110
  31. data/doc/CVS/Entries +0 -3
  32. data/doc/CVS/Entries.Log +0 -2
  33. data/doc/CVS/Repository +0 -1
  34. data/doc/CVS/Root +0 -1
  35. data/doc/classes/CVS/Entries +0 -1
  36. data/doc/classes/CVS/Entries.Log +0 -1
  37. data/doc/classes/CVS/Repository +0 -1
  38. data/doc/classes/CVS/Root +0 -1
  39. data/doc/classes/FireRuby/CVS/Entries +0 -1
  40. data/doc/classes/FireRuby/CVS/Entries.Log +0 -7
  41. data/doc/classes/FireRuby/CVS/Repository +0 -1
  42. data/doc/classes/FireRuby/CVS/Root +0 -1
  43. data/doc/classes/FireRuby/Connection.src/CVS/Entries +0 -1
  44. data/doc/classes/FireRuby/Connection.src/CVS/Repository +0 -1
  45. data/doc/classes/FireRuby/Connection.src/CVS/Root +0 -1
  46. data/doc/classes/FireRuby/Database.src/CVS/Entries +0 -1
  47. data/doc/classes/FireRuby/Database.src/CVS/Repository +0 -1
  48. data/doc/classes/FireRuby/Database.src/CVS/Root +0 -1
  49. data/doc/classes/FireRuby/FireRubyError.src/CVS/Entries +0 -1
  50. data/doc/classes/FireRuby/FireRubyError.src/CVS/Repository +0 -1
  51. data/doc/classes/FireRuby/FireRubyError.src/CVS/Root +0 -1
  52. data/doc/classes/FireRuby/Generator.src/CVS/Entries +0 -1
  53. data/doc/classes/FireRuby/Generator.src/CVS/Repository +0 -1
  54. data/doc/classes/FireRuby/Generator.src/CVS/Root +0 -1
  55. data/doc/classes/FireRuby/ResultSet.src/CVS/Entries +0 -1
  56. data/doc/classes/FireRuby/ResultSet.src/CVS/Repository +0 -1
  57. data/doc/classes/FireRuby/ResultSet.src/CVS/Root +0 -1
  58. data/doc/classes/FireRuby/Statement.src/CVS/Entries +0 -1
  59. data/doc/classes/FireRuby/Statement.src/CVS/Repository +0 -1
  60. data/doc/classes/FireRuby/Statement.src/CVS/Root +0 -1
  61. data/doc/classes/FireRuby/Transaction.src/CVS/Entries +0 -1
  62. data/doc/classes/FireRuby/Transaction.src/CVS/Repository +0 -1
  63. data/doc/classes/FireRuby/Transaction.src/CVS/Root +0 -1
  64. data/doc/files/CVS/Entries +0 -1
  65. data/doc/files/CVS/Repository +0 -1
  66. data/doc/files/CVS/Root +0 -1
  67. data/examples/CVS/Entries +0 -2
  68. data/examples/CVS/Repository +0 -1
  69. data/examples/CVS/Root +0 -1
  70. data/lib/CVS/Entries +0 -6
  71. data/lib/CVS/Repository +0 -1
  72. data/lib/CVS/Root +0 -1
  73. data/test/CVS/Entries +0 -20
  74. data/test/CVS/Repository +0 -1
  75. data/test/CVS/Root +0 -1
data/lib/fireruby.rb CHANGED
@@ -1,22 +1,22 @@
1
- #-------------------------------------------------------------------------------
2
- # fireruby.rb
3
- #-------------------------------------------------------------------------------
4
- # Copyright � Peter Wood, 2005
5
- #
6
- # The contents of this file are subject to the Mozilla Public License Version
7
- # 1.1 (the "License"); you may not use this file except in compliance with the
8
- # License. You may obtain a copy of the License at
9
- #
10
- # http://www.mozilla.org/MPL/
11
- #
12
- # Software distributed under the License is distributed on an "AS IS" basis,
13
- # WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
14
- # the specificlanguage governing rights and limitations under the License.
15
- #
16
- # The Original Code is the FireRuby extension for the Ruby language.
17
- #
18
- # The Initial Developer of the Original Code is Peter Wood. All Rights
19
- # Reserved.
20
-
21
- require 'fr_lib'
22
- require 'SQLType'
1
+ #-------------------------------------------------------------------------------
2
+ # fireruby.rb
3
+ #-------------------------------------------------------------------------------
4
+ # Copyright � Peter Wood, 2005
5
+ #
6
+ # The contents of this file are subject to the Mozilla Public License Version
7
+ # 1.1 (the "License"); you may not use this file except in compliance with the
8
+ # License. You may obtain a copy of the License at
9
+ #
10
+ # http://www.mozilla.org/MPL/
11
+ #
12
+ # Software distributed under the License is distributed on an "AS IS" basis,
13
+ # WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
14
+ # the specificlanguage governing rights and limitations under the License.
15
+ #
16
+ # The Original Code is the FireRuby extension for the Ruby language.
17
+ #
18
+ # The Initial Developer of the Original Code is Peter Wood. All Rights
19
+ # Reserved.
20
+
21
+ require 'fr_lib'
22
+ require 'SQLType'
data/lib/fr_lib.so CHANGED
Binary file
data/lib/mkdoc CHANGED
@@ -1 +1 @@
1
- rdoc -m README src.rb README
1
+ rdoc -m README src.rb README
data/lib/src.rb CHANGED
@@ -1,1795 +1,1795 @@
1
- #
2
- # This file is a stand-in that allows for the generation of rdoc documentation
3
- # for the FireRuby extension for the Ruby programming language. The extension
4
- # is coded in C and documented with Doxygen comments, so this file is used to
5
- # generate the native Ruby documentation instead.
6
- #
7
-
8
- #
9
- # This module contains all of the classes and definitions relating to the
10
- # FireRuby extension for the Ruby language.
11
- #
12
- module FireRuby
13
- #
14
- # This class provides the exception type used by the FireRuby library.
15
- #
16
- class FireRubyException
17
- #
18
- # This is the constructor for the FireRubyError class.
19
- #
20
- # ==== Parameters
21
- # message:: A string containing the error message for the object.
22
- #
23
- def initialize(message)
24
- end
25
-
26
-
27
- #
28
- # This is the accessor for the error message attribute
29
- #
30
- def message
31
- end
32
-
33
-
34
- #
35
- # This is the accessor for the SQL code attribute.
36
- #
37
- def sql_code
38
- end
39
-
40
-
41
- #
42
- # This is the accessor for the database code attribute.
43
- #
44
- def db_code
45
- end
46
-
47
-
48
- #
49
- # This function generates a simple description string for a FireRubyError
50
- # object.
51
- #
52
- def to_s
53
- end
54
- end
55
-
56
-
57
- #
58
- # This class represents an existing database that can be connected to. It
59
- # also provides functionality to allow for the creation of new databases.
60
- #
61
- class Database
62
- #
63
- # This is the constructor for the Database class.
64
- #
65
- # ==== Parameters
66
- # file:: A string containing the database file specifier. This can
67
- # include details for a remote server if needed.
68
- # set:: A string containing the name of the character set to be
69
- # used with the database. Defaults to nil.
70
- #
71
- def initialize(file, set=nil)
72
- end
73
-
74
-
75
- #
76
- # This is the accessor for the database file specification attribute.
77
- #
78
- def file
79
- end
80
-
81
-
82
- #
83
- # This method attempts to establish a connection to a database. If
84
- # successful then a Connection instance is returned. If a block is
85
- # provided to the method then the connection is closed after the
86
- # block completes. If a block is specified the connection is provided
87
- # as a parameter to the block.
88
- #
89
- # ==== Parameters
90
- # user:: The user name to be used in making the connection. This
91
- # defaults to nil.
92
- # password:: The password to be used in making the connection. This
93
- # defaults to nil.
94
- # options:: A Hash of connection options. This should be made up of
95
- # key/setting pairs where the keys are from the list that
96
- # is defined within the Connection class. The settings are
97
- # particular to the key, see the documentation for the
98
- # Connection class for more details.
99
- #
100
- # ==== Exceptions
101
- # Exception:: Thrown whenever a problem occurs connecting with the
102
- # database.
103
- #
104
- def connect(user=nil, password=nil, options=nil)
105
- yield(connection)
106
- end
107
-
108
-
109
- #
110
- # This method attempts to drop the database referred to by the details
111
- # in a Database object.
112
- #
113
- # ==== Parameters
114
- # user:: The user name to be used in dropping the database.
115
- # password:: The password to be used in dropping the database.
116
- #
117
- # ==== Exceptions
118
- # FireRubyError:: Thrown whenever a problem occurs dropping the database
119
- # instance.
120
- #
121
- def drop(user, password)
122
- end
123
-
124
-
125
- #
126
- # This method can be used to programmatically created a database file.
127
- # If successful this method returns a Database object.
128
- #
129
- # ==== Parameters
130
- # file:: A string containing the path and name of the database file
131
- # to be created.
132
- # user:: A string containing the user name that will be used in
133
- # creating the file.
134
- # password:: A string containing the user password that will be used in
135
- # creating the file.
136
- # size:: The page size setting to be used with the new database file.
137
- # This should be 1024, 2048, 4096 or 8192. Defaults to 1024.
138
- # set:: The name of the default character set to be assigned to the
139
- # new database file. If this parameter is specifed then the
140
- # Database object created by the call will use it to whenever
141
- # a connection request is made. Defaults to nil.
142
- #
143
- # ==== Exceptions
144
- # Exception:: Generated whenever an invalid parameter is specified or a
145
- # problem occurs creating the database file.
146
- #
147
- def Database.create(file, user, password, size=1024, set=nil)
148
- end
149
-
150
-
151
- #
152
- # This method fetches the name of the character set currently assigned
153
- # to a Database object. This can return nil to indicate that a explicit
154
- # character set has not been assigned.
155
- #
156
- def character_set
157
- end
158
-
159
-
160
- #
161
- # This method allows the specification of a database character set that
162
- # will be used when creating connections to a database. The value set by
163
- # this method can be overridden by providing an alternative in the connect
164
- # call. To remove a character set specification from a Database object
165
- # pass nil to this method.
166
- #
167
- # ==== Parameters
168
- # set:: A string containing the name of the database character set.
169
- #
170
- def character_set=(set)
171
- end
172
- end
173
-
174
-
175
- #
176
- # This class represents a connection with a Firebird database.
177
- #
178
- class Connection
179
- # A definition for a connection option. This option should be given a
180
- # setting of either true or false.
181
- MARK_DATABASE_DAMAGED = 17
182
-
183
-
184
- # A definition for a connection option. This option should be given a
185
- # setting of Connection::WRITE_ASYNCHRONOUS or
186
- # Connection::WRITE_SYNCHRONOUS
187
- WRITE_POLICY = 24
188
-
189
-
190
- # A definition for a connection option. This option should be given a
191
- # string setting which should be the name of the character set to be
192
- # used by the connection.
193
- CHARACTER_SET = 48
194
-
195
-
196
- # A definition for a connection option. This option should be given a
197
- # string setting which should be the name of the message file to be used
198
- # by the connection.
199
- MESSAGE_FILE = 47
200
-
201
-
202
- # A definition for a connection option. This option should be given a
203
- # an integer setting. Values between 1 and 255 are valid, with 75 being
204
- # the default.
205
- NUMBER_OF_CACHE_BUFFERS = 5
206
-
207
-
208
- # A definition for a connection option. This option should be given a
209
- # string value which should be the database DBA user name.
210
- DBA_USER_NAME = 19
211
-
212
-
213
- # A definition for a possible setting to accompany the WRITE_POLICY
214
- # connection setting.
215
- WRITE_ASYNCHONOUS = 0
216
-
217
-
218
- # A definition for a possible setting to accompany the WRITE_POLICY
219
- # connection setting.
220
- WRITE_SYNCHONOUS = 1
221
-
222
-
223
- #
224
- # This is the constructor for the Connection class.
225
- #
226
- # ==== Parameters
227
- # database:: A reference to the Database object to be connected to.
228
- # user:: A reference to the user name to be used in making the
229
- # database connection. Defaults to nil.
230
- # password:: A reference to the user password to be used in making the
231
- # connection. Defaults to nil.
232
- # options:: A Hash containing the options to be applied to the new
233
- # connection. The hash will contain key/setting values, with
234
- # the keys being based on the option constants defined within
235
- # the Connection class. Individual options have differing
236
- # value requirements. See the option documentation entries
237
- # for further details. Defaults to nil.
238
- #
239
- # ==== Exceptions
240
- # Exception:: Generated whenever an invalid database is specified to
241
- # the method or an issue occurs establishing the database
242
- # connection.
243
- #
244
- def initialize(database, user, password, options)
245
- end
246
-
247
-
248
- #
249
- # This method is used to determine whether a Connection object represents
250
- # an active database connection.
251
- #
252
- def open?
253
- end
254
-
255
-
256
- #
257
- # This method is used to determine whether a Connection object represents
258
- # an inactive database connection.
259
- #
260
- def closed?
261
- end
262
-
263
-
264
- #
265
- # This method detaches a Connection object from a database. The object
266
- # may not be used for database functionality following a successful call
267
- # to this method. The close method will fail if there are outstanding
268
- # transactions for a connection.
269
- #
270
- # ==== Exceptions
271
- # Exception:: Generated whenever the connection has at least one open
272
- # transaction or an error occurs closing the connection.
273
- #
274
- def close
275
- end
276
-
277
-
278
- #
279
- # This is the accessor method for the database attribute.
280
- #
281
- def database
282
- end
283
-
284
-
285
- #
286
- # This method retrieves the user name that was used in creating a
287
- # Connection object.
288
- #
289
- def user
290
- end
291
-
292
-
293
- #
294
- # This method generates a simple descriptive string for a Connection
295
- # object.
296
- #
297
- def to_s
298
- end
299
-
300
-
301
- #
302
- # This method starts a new transaction against a connection. A successful
303
- # call to this method returns a Transaction object. The transaction that
304
- # is started relates to the Connection it was called upon only. To start
305
- # a transaction that covers multiple connections use the Transaction
306
- # class. This method accepts a block, taking a single parameter which
307
- # will be the transaction created. This transaction is committed if the
308
- # block completes normally or rolls back if an exception is thrown from
309
- # the block.
310
- #
311
- # ==== Exceptions
312
- # Exception:: Thrown whenever a problem occurs starting the transaction.
313
- #
314
- def start_transaction
315
- yield transaction
316
- end
317
-
318
-
319
- #
320
- # This function executes a SQL statement against a connection. If the
321
- # statement represented a SQL query then a ResultSet object is returned.
322
- # If the statement was a non-query SQL statement then an Integer is
323
- # returned indicating the number of rows affected by the statement. For
324
- # all other types of statement the method returns nil. The method also
325
- # accepts a block that takes a single parameter. This block will be
326
- # executed once for each row in any result set generated.
327
- #
328
- # ==== Parameters
329
- # sql:: The SQL statement to be executed.
330
- # transaction:: The transaction to execute the SQL statement within.
331
- #
332
- # ==== Exceptions
333
- # Exception:: Generated if an error occurs executing the SQL statement.
334
- #
335
- def execute(sql, transaction)
336
- yield(row)
337
- end
338
-
339
-
340
- #
341
- # This function executes a SQL statement against a connection. This
342
- # differs from the execute method in that an anonymous transaction is
343
- # used in executing the statement. The output from this method is the
344
- # same as for the execute method. The method also accepts a block that
345
- # takes a single parameter. This block will be executed once for each
346
- # row in any result set generated.
347
- #
348
- # ==== Parameters
349
- # sql:: The SQL statement to be executed.
350
- #
351
- # ==== Exceptions
352
- # Exception:: Generated whenever a problem occurs executing the SQL
353
- # statement.
354
- #
355
- def execute_immediate(sql)
356
- yield(row)
357
- end
358
- end
359
-
360
-
361
- #
362
- # This class represents a Firebird database transaction. There may be
363
- # multiple transaction outstanding against a connection at any one time.
364
- #
365
- class Transaction
366
- TPB_VERSION_1 = 1
367
- TPB_VERSION_3 = 3
368
- TPB_CONSISTENCY = 1
369
- TPB_CONCURRENCY = 2
370
- TPB_SHARED = 3
371
- TPB_PROTECTED = 4
372
- TPB_EXCLUSIVE = 5
373
- TPB_WAIT = 6
374
- TPB_NO_WAIT = 7
375
- TPB_READ = 8
376
- TPB_WRITE = 9
377
- TPB_LOCK_READ = 10
378
- TPB_LOCK_WRITE = 11
379
- TPB_VERB_TIME = 12
380
- TPB_COMMIT_TIME = 13
381
- TPB_IGNORE_LIMBO = 14
382
- TPB_READ_COMMITTED = 15
383
- TPB_AUTO_COMMIT = 16
384
- TPB_REC_VERSION = 17
385
- TPB_NO_REC_VERSION = 18
386
- TPB_RESTART_REQUESTS = 19
387
- # Transaction parameter buffer value constants.
388
- TPB_NO_AUTO_UNDO = 20
389
-
390
-
391
- #
392
- # This is the constructor for the Transaction class.
393
- #
394
- # ==== Parameters
395
- # connections:: Either a single instance of the Connection class or
396
- # an array of Connection instances to specify a
397
- # multi-database transaction.
398
- #
399
- # ==== Exceptions
400
- # Exception:: Generated whenever the method is passed an invalid
401
- # parameter or a problem occurs creating the transaction.
402
- #
403
- def initialize(connections)
404
- end
405
-
406
-
407
- #
408
- # This method is used to determine whether a Transaction object is still
409
- # valid for use (i.e. commit or rollback has not been called for the
410
- # Transaction).
411
- #
412
- def active?
413
- end
414
-
415
-
416
- #
417
- # This is the accessor for the connections attribute. This method returns
418
- # an array of the connections that the transaction applies to.
419
- #
420
- def connections
421
- end
422
-
423
-
424
- #
425
- # This method is used to determine whether a given Transaction applies to
426
- # a specified Connection.
427
- #
428
- # ==== Parameters
429
- # connection:: A reference to the Connection object to perform the test
430
- # for.
431
- #
432
- def for_connection?(connection)
433
- end
434
-
435
-
436
- #
437
- # This method commits the details outstanding against a Transaction
438
- # object. The Transaction object may not be reused after a successful
439
- # call to this method.
440
- #
441
- # ==== Exceptions
442
- # Exception:: Generated whenever a problem occurs committing the details
443
- # of the transaction.
444
- #
445
- def commit
446
- end
447
-
448
-
449
- #
450
- # This method rolls back the details outstanding against a Transaction
451
- # object. The Transaction object may not be reused after a successful
452
- # call to this method.
453
- #
454
- # ==== Exceptions
455
- # Exception:: Generated whenever a problem occurs rolling back the
456
- # details of the transaction.
457
- #
458
- def rollback
459
- end
460
-
461
-
462
- #
463
- # This method executes a SQL statement using a Transaction object. This
464
- # method will only work whenever a Transaction object applies to a
465
- # single Connection as it would otherwise be impossible to determine
466
- # which connection to execute against. If the statement executed was a
467
- # SQL query then the method returns a ResultSet object. For non-query SQL
468
- # statements (insert, update or delete) the method returns an Integer that
469
- # contains the number of rows affected by the statement. For all other
470
- # statements the method returns nil. The method also accepts a block that
471
- # takes a single parameter. If the SQL statement was a query the block
472
- # will be invoked and passed each row retrieved.
473
- #
474
- # ==== Parameters
475
- # sql:: A string containing the SQL statement to be executed.
476
- #
477
- # ==== Exceptions
478
- # Exception:: Generated whenever the Transaction object represents more
479
- # than one connection or a problem occurs executing the SQL
480
- # statement.
481
- #
482
- def execute(sql)
483
- yield(row)
484
- end
485
-
486
-
487
- #
488
- # This method allows for the creation of a Transaction object with
489
- # non-standard settings.
490
- #
491
- # ==== Parameters
492
- # connections:: Either a single Connection object or an array of
493
- # Connection objects that the new Transaction will
494
- # be associated with.
495
- # parameters:: An array of the parameters to be used in creating
496
- # the new constants. Populate this from the TPB
497
- # constants defined within the class.
498
- #
499
- # ==== Exceptions
500
- # FireRubyError:: Generated whenever a problem occurs creating the
501
- # transaction.
502
- #
503
- def Transaction.create(connections, parameters)
504
- end
505
- end
506
-
507
-
508
- #
509
- # This class represents a prepared SQL statement that may be executed more
510
- # than once.
511
- #
512
- class Statement
513
- # A definition for a SQL statement type constant.
514
- SELECT_STATEMENT = 1
515
-
516
- # A definition for a SQL statement type constant.
517
- INSERT_STATEMENT = 2
518
-
519
- # A definition for a SQL statement type constant.
520
- UPDATE_STATEMENT = 3
521
-
522
- # A definition for a SQL statement type constant.
523
- DELETE_STATEMENT = 4
524
-
525
- # A definition for a SQL statement type constant.
526
- DDL_STATEMENT = 5
527
-
528
- # A definition for a SQL statement type constant.
529
- GET_SEGMENT_STATEMENT = 6
530
-
531
- # A definition for a SQL statement type constant.
532
- PUT_SEGMENT_STATEMENT = 7
533
-
534
- # A definition for a SQL statement type constant.
535
- EXECUTE_PROCEDURE_STATEMENT = 8
536
-
537
- # A definition for a SQL statement type constant.
538
- START_TRANSACTION_STATEMENT = 9
539
-
540
- # A definition for a SQL statement type constant.
541
- COMMIT_STATEMENT = 10
542
-
543
- # A definition for a SQL statement type constant.
544
- ROLLBACK_STATEMENT = 11
545
-
546
- # A definition for a SQL statement type constant.
547
- SELECT_FOR_UPDATE_STATEMENT = 12
548
-
549
- # A definition for a SQL statement type constant.
550
- SET_GENERATOR_STATEMENT = 13
551
-
552
- # A definition for a SQL statement type constant.
553
- SAVE_POINT_STATEMENT = 14
554
-
555
- #
556
- # This is the constructor for the Statement class.
557
- #
558
- # ==== Parameters
559
- # connection:: The Connection object that the SQL statement will be
560
- # executed through.
561
- # transaction:: The Transaction object that the SQL statement will be
562
- # executed under.
563
- # sql:: The SQL statement to be prepared for execution.
564
- # dialect:: The Firebird dialect to be used in preparing the SQL
565
- # statement.
566
- #
567
- def initialize(connection, transaction, sql, dialect)
568
- end
569
-
570
-
571
- #
572
- # This is the accessor for the connection attribute.
573
- #
574
- def connection
575
- end
576
-
577
-
578
- #
579
- # This is the accessor for the transaction attribute.
580
- #
581
- def transaction
582
- end
583
-
584
-
585
- #
586
- # This is the accessor for the SQL statement attribute.
587
- #
588
- def sql
589
- end
590
-
591
-
592
- #
593
- # This is the accessor for the dialect attribute.
594
- #
595
- def dialect
596
- end
597
-
598
-
599
- #
600
- # This method is used to determine the type of a SQL statement. The method
601
- # will return one of the constant SQL types defined within the class.
602
- #
603
- def type
604
- end
605
-
606
-
607
- #
608
- # This method fetches a count of the number of dynamic parameters for
609
- # a statement object (i.e. the number of parameters that must be provided
610
- # with values before the SQL statement can be executed).
611
- #
612
- def parameter_count
613
- end
614
-
615
-
616
- #
617
- # This method executes the SQL statement within a Statement object. This
618
- # method returns a ResultSet object if the statement executed was a SQL
619
- # query. For non-query SQL statements (insert, update or delete) it
620
- # returns an Integer indicating the number of affected rows. For all other
621
- # statements the method returns nil. This method accepts a block taking a
622
- # single parameter. If this block is provided and the statement is a query
623
- # then the rows returned by the query will be passed, one at a time, to
624
- # the block.
625
- #
626
- # ==== Exception
627
- # Exception:: Generated if the Statement object actual requires some
628
- # parameters or a problem occurs executing the SQL statement.
629
- #
630
- def execute
631
- yield row
632
- end
633
-
634
-
635
- #
636
- # This method executes the SQL statement within a Statement object and
637
- # passes it a set of parameters. Parameterized statements use question
638
- # marks as place holders for values that may change between calls to
639
- # execute the statement. This method returns a ResultSet object if the
640
- # statement executed was a SQL query. If the statement was a non-query SQL
641
- # statement (insert, update or delete) then the method returns a count of
642
- # the number of rows affected. For all other types of statement the method
643
- # returns nil. This method accepts a block taking a single parameter. If
644
- # this block is provided and the statement is a query then the rows
645
- # returned by the query will be passed, one at a time, to the block.
646
- #
647
- # ==== Parameters
648
- # parameters:: An array of the parameters for the statement. An effort
649
- # will be made to convert the values passed in to the
650
- # appropriate types but no guarantees are made (especially
651
- # in the case of text fields, which will simply use to_s
652
- # if the object passed is not a String).
653
- #
654
- # ==== Exception
655
- # Exception:: Generated whenever a problem occurs translating one of the
656
- # input parameters or executing the SQL statement.
657
- #
658
- def execute_for(parameters)
659
- yield row
660
- end
661
-
662
-
663
- #
664
- # This method releases the database resources associated with a Statement
665
- # object and should be explicitly called when a Statement object is of
666
- # no further use.
667
- #
668
- # ==== Exceptions
669
- # FireRubyError:: Generated whenever a problem occurs closing the
670
- # statement object.
671
- #
672
- def close
673
- end
674
- end
675
-
676
-
677
- #
678
- # This class represents the results of a SQL query executed against a
679
- # database. The viable lifespan of a ResultSet object is limited by the
680
- # transaction that was used in it's creation. Once this transaction has
681
- # been committed or rolled back all related ResultSet object are invalidated
682
- # and can no longer be used.
683
- #
684
- class ResultSet
685
- include Enumerable
686
-
687
- #
688
- # This is the constructor for the ResultSet object.
689
- #
690
- # ==== Parameters
691
- # connection:: A reference to the Connection object that will be used
692
- # to execute the SQL query.
693
- # transaction:: A reference to the Transaction object that will be used
694
- # in executing the SQL query.
695
- # sql:: A reference to a String containing the SQL query that
696
- # will be executed.
697
- # dialect:: A reference to an integer containing the Firebird dialect
698
- # to be used in executing the SQL statement.
699
- #
700
- # ==== Exceptions
701
- # FireRubyException:: Generated whenever a non-query SQL statement is
702
- # specified, an invalid connection or transaction is
703
- # provided or a problem occurs executing the SQL
704
- # against the database.
705
- #
706
- def initialize(connection, transaction, sql, dialect)
707
- end
708
-
709
-
710
- #
711
- # This is the accessor for the connection attribute.
712
- #
713
- def connection
714
- end
715
-
716
-
717
- #
718
- # This is the accessor for the transaction attribute.
719
- #
720
- def transaction
721
- end
722
-
723
-
724
- #
725
- # This is the accessor for the sql attribute.
726
- #
727
- def sql
728
- end
729
-
730
-
731
- #
732
- # This is the accessor for the dialect attribute.
733
- #
734
- def dialect
735
- end
736
-
737
-
738
- #
739
- # This method fetches a count of the number of columns in a row of data
740
- # that the ResultSet can fetch.
741
- #
742
- def column_count
743
- end
744
-
745
-
746
- #
747
- # This method fetches the name associated with a specified column for a
748
- # ResultSet object.
749
- #
750
- # ==== Parameters
751
- # column:: A reference to the column number to fetch the details for.
752
- # Column numbers start at zero.
753
- #
754
- def column_name(column)
755
- end
756
-
757
-
758
- #
759
- # This method fetches the alias associated with a specified column for a
760
- # ResultSet object.
761
- #
762
- # ==== Parameters
763
- # column:: A reference to the column number to fetch the details for.
764
- # Column numbers start at zero.
765
- #
766
- def column_alias(column)
767
- end
768
-
769
-
770
- #
771
- # This method fetches the table name associated with a specified column
772
- # for a ResultSet object.
773
- #
774
- # ==== Parameters
775
- # column:: A reference to the column number to fetch the details for.
776
- # Column numbers start at zero.
777
- #
778
- def column_table(column)
779
- end
780
-
781
-
782
- #
783
- # This method fetches a single rows worth of data from the ResultSet
784
- # object. If the set contains more rows then an array containing the
785
- # row data will be retrieved. If the ResultSet is exhausted (i.e. all
786
- # rows have been fetched) then nil is returned. Translation of the row
787
- # data into an appropriate Ruby type is performed on the row data that
788
- # is extracted.
789
- #
790
- def fetch
791
- end
792
-
793
-
794
- #
795
- # This method is used to determine if all of the rows have been retrieved
796
- # from a ResultSet object. This method will always return false until
797
- # the fetch method has been called at least once so it cannot be used to
798
- # detect a result set that returns no rows.
799
- #
800
- def exhausted?
801
- end
802
-
803
-
804
- #
805
- # This method fetches a count of the total number of rows retrieved
806
- # from a result set.
807
- #
808
- def row_count
809
- end
810
-
811
-
812
- #
813
- # This method provides an iterator for the (remaining) rows contained in
814
- # a ResultSet object.
815
- #
816
- # ==== Parameters
817
- # block:: A block that takes a single parameter. This will be called for
818
- # and passed each remaining row (as per the fetch method) from
819
- # the ResultSet.
820
- #
821
- def each(&block)
822
- end
823
-
824
-
825
- #
826
- # This method releases the database resources associated with a ResultSet
827
- # object and should be explicitly called when a ResultSet object is of
828
- # no further use. The method is implicitly called if the rows available
829
- # from a ResultSet are exhausted but calling this method at that time
830
- # will not cause an error.
831
- #
832
- # ==== Exceptions
833
- # FireRubyError:: Generated whenever a problem occurs closing the result
834
- # set object.
835
- #
836
- def close
837
- end
838
-
839
- #
840
- # This method retrieves the base SQL type for a column of data within a
841
- # ResultSet object. The method returns one of the base types defined in
842
- # the SQLType class but does not return an actual SQLType object.
843
- #
844
- # ==== Parameters
845
- # index:: The offset from the ResultSet first column of the column to
846
- # return the type information for.
847
- #
848
- def get_base_type(index)
849
- end
850
- end
851
-
852
-
853
- #
854
- # This class models a row of data fetched as part of a SQL query.
855
- #
856
- class Row
857
- include Enumerable
858
-
859
- #
860
- # This is the constructor for the Row class. This method shouldn't really
861
- # be used as Row objects are automatically created by ResultSets.
862
- #
863
- # ==== Parameters
864
- # results:: The ResultSet object that the row relates to.
865
- # data:: An array containing the row data values.
866
- # number:: The row number for the new row.
867
- #
868
- def initialize(results, data, number)
869
- end
870
-
871
- #
872
- # This is the accessor for the row number attribute. This will generally
873
- # reflect the order the row was fetched from the result set in, with 1
874
- # being the first row retrieved.
875
- #
876
- def number
877
- end
878
-
879
-
880
- #
881
- # This method fetches a count of the number of columns of data that are
882
- # available from a row.
883
- #
884
- def column_count
885
- end
886
-
887
-
888
- #
889
- # This method fetches the name of a column within a row of data.
890
- #
891
- # ==== Parameters
892
- # index:: The index of the column to fetch the name for. The first
893
- # column in the row is at offset zero.
894
- #
895
- def column_name(index)
896
- end
897
-
898
-
899
- #
900
- # This method fetches the alias of a column within a row of data.
901
- #
902
- # ==== Parameters
903
- # index:: The index of the column to fetch the alias for. The first
904
- # column in the row is at offset zero.
905
- #
906
- def column_alias(index)
907
- end
908
-
909
-
910
- #
911
- # This method fetches the value associated with a column within a Row
912
- # object.
913
- #
914
- # ==== Parameters
915
- # index:: Either the offset of the column to retrieve the value of or
916
- # the alias of the column to retrieve the value of (column alias
917
- # comparisons are case sensitive).
918
- #
919
- def [](index)
920
- end
921
-
922
-
923
- #
924
- # This method iterates over the contents of a Row object. The block
925
- # specified for the method should accept two parameters; one for the
926
- # column alias and one for the column value.
927
- #
928
- def each
929
- yield column, vlaue
930
- end
931
-
932
-
933
- #
934
- # This method iterates over the column names for a Row class.
935
- #
936
- def each_key
937
- yield column
938
- end
939
-
940
-
941
- #
942
- # This method iterators over the column values for a Row class.
943
- #
944
- def each_value
945
- yield value
946
- end
947
-
948
-
949
- #
950
- # An implementation of the Hash#fetch method for the Row class. The
951
- # method accepts a block but this should not be specified if a value
952
- # for the alternative parameter is specified.
953
- #
954
- # ==== Parameters
955
- # key:: A string containing the column alias to retrieve.
956
- # alternative:: A reference to the alternative value to be returned if
957
- # the keyed value is not found. Defaults to nil.
958
- #
959
- def fetch(key, alternative=nil)
960
- yield key
961
- end
962
-
963
-
964
- #
965
- # This method is used to determine whether a Row object contains a given
966
- # column alias.
967
- #
968
- # ==== Parameters
969
- # name:: A String containing the column name to check for.
970
- #
971
- def has_key?(name)
972
- end
973
-
974
-
975
- #
976
- # This method is used to determine whether a Row object contains a given
977
- # column name.
978
- #
979
- # ==== Parameters
980
- # name:: A String containing the column name to check for.
981
- #
982
- def has_column?(name)
983
- end
984
-
985
-
986
- #
987
- # This method is used to determine whether a Row object contains a given
988
- # column alias.
989
- #
990
- # ==== Parameters
991
- # name:: A String containing the column alias to check for.
992
- #
993
- def has_alias?(name)
994
- end
995
-
996
-
997
- #
998
- # This method is used to determine whether a Row object contains a given
999
- # column value.
1000
- #
1001
- # ==== Parameters
1002
- # value:: A reference to an object value to be checked for.
1003
- #
1004
- def has_value?(value)
1005
- end
1006
-
1007
-
1008
- #
1009
- # This method retrieves an array of column aliases for a Row object.
1010
- #
1011
- def keys
1012
- end
1013
-
1014
-
1015
- #
1016
- # This method retrieves an array of column names for a Row object.
1017
- #
1018
- def names
1019
- end
1020
-
1021
-
1022
- #
1023
- # This method retrieves an array of column aliases for a Row object.
1024
- #
1025
- def aliases
1026
- end
1027
-
1028
-
1029
- #
1030
- # This method retrieves an array of column values for a Row object.
1031
- #
1032
- def values
1033
- end
1034
-
1035
-
1036
- #
1037
- # This method returns an array of the Row elements for which the specified
1038
- # block returns true.
1039
- #
1040
- def select
1041
- yield column, value
1042
- end
1043
-
1044
-
1045
- #
1046
- # This method retrieves an Array containing the values from a Row object.
1047
- # Each value is represented as an Array containing a column name and the
1048
- # associated column value.
1049
- #
1050
- def to_a
1051
- end
1052
-
1053
-
1054
- #
1055
- # This method retrieves a Hash created from a Row objects values. The Row
1056
- # objects column names will be used as a key on to the column values.
1057
- #
1058
- def to_hash
1059
- end
1060
-
1061
-
1062
- #
1063
- # This method returns an array of column values based on a list of column
1064
- # aliases.
1065
- #
1066
- # ==== Parameters
1067
- # names:: One or more Strings containing the names of the columns to
1068
- # retrieve values for.
1069
- #
1070
- def values_at(*names)
1071
- end
1072
-
1073
- #
1074
- # This method retrieves the base SQL type for a column of data within a
1075
- # Row object. The method returns one of the base types defined in the
1076
- # SQLType class but does not return an actual SQLType object.
1077
- #
1078
- # ==== Parameters
1079
- # index:: The offset from the Row first column of the column to return
1080
- # the type information for.
1081
- #
1082
- def get_base_type(index)
1083
- end
1084
- end
1085
-
1086
- #
1087
- # This class represents Blob data fetched from the database. The class defers
1088
- # the actual loading of the blob until requested. The class is somewhat basic
1089
- # and maybe expanded upon in later releases.
1090
- #
1091
- class Blob
1092
- #
1093
- # This is the constructor for the Blob class. This shouldn't really be
1094
- # used outside of the FireRuby library.
1095
- #
1096
- def initialize
1097
- end
1098
-
1099
-
1100
- #
1101
- # This method loads the entire data set for a blob as a string.
1102
- #
1103
- def to_s
1104
- end
1105
-
1106
-
1107
- #
1108
- # This method closes a blob, freeing any resources associated with it.
1109
- #
1110
- def close
1111
- end
1112
-
1113
-
1114
- #
1115
- # This method loads the segments of a blob one after another. The blob
1116
- # segments are passed as strings to the block passed to the method.
1117
- #
1118
- def each
1119
- yield segment
1120
- end
1121
- end
1122
-
1123
-
1124
- #
1125
- # This class represents a Firebird generator entity.
1126
- #
1127
- class Generator
1128
- #
1129
- # This is the constructor for the Generator class. Note, this method
1130
- # assumes that the named generator already exists. If it doesn't then
1131
- # the object will be constructed but will fail during use.
1132
- #
1133
- # ==== Parameters
1134
- # name:: A string containing the generator name.
1135
- # connection:: A reference to the Connection object that will be used
1136
- # to access the generator.
1137
- #
1138
- def initialize(name, connection)
1139
- end
1140
-
1141
-
1142
- #
1143
- # This is the accessor for the name attribute.
1144
- #
1145
- def name
1146
- end
1147
-
1148
-
1149
- #
1150
- # This is the accessor for the connection attribute.
1151
- #
1152
- def connection
1153
- end
1154
-
1155
-
1156
- #
1157
- # This method fetches the last value generator from a generator.
1158
- #
1159
- # ==== Exceptions
1160
- # Exception:: Generated whenever a problem occurs accessing the
1161
- # database generator.
1162
- #
1163
- def last
1164
- end
1165
-
1166
-
1167
- #
1168
- # This method drops a generator from the database. After a successful
1169
- # call to this method the Generator object may not be used to obtain
1170
- # values unless it is recreated.
1171
- #
1172
- # ==== Exceptions
1173
- # Exception:: Generated whenever a problem occurs dropping the generator
1174
- # from the database.
1175
- #
1176
- def drop
1177
- end
1178
-
1179
-
1180
- #
1181
- # This method fetches the next value, depending on a specified increment,
1182
- # from a generator.
1183
- #
1184
- # ==== Parameters
1185
- # step:: The step interval to be applied to the generator to obtain the
1186
- # next value.
1187
- #
1188
- # ==== Exceptions
1189
- # Exception:: Generated whenever a problem occurs accessing the
1190
- # database generator.
1191
- #
1192
- def next(step)
1193
- end
1194
-
1195
-
1196
- #
1197
- # This method is used to determine whether a named generator exists
1198
- # within a database.
1199
- #
1200
- # ==== Parameters
1201
- # name:: A string containing the generator name to check for.
1202
- # connection:: A reference to the Connection object to be used in
1203
- # performing the check.
1204
- #
1205
- # ==== Exceptions
1206
- # Exception:: Generated whenever a problem occurs determining the
1207
- # existence of the generator.
1208
- #
1209
- def Generator.exists?(name, connection)
1210
- end
1211
-
1212
-
1213
- #
1214
- # This method creates a new generator within a database. This method
1215
- # returns a Generator object is successful.
1216
- #
1217
- # ==== Parameters
1218
- # name:: A string containing the name for the new generator.
1219
- # connection:: A reference to the Connection object that will be used to
1220
- # create the generator.
1221
- #
1222
- # ==== Exceptions
1223
- # Exception:: Generated whenever a problem occurs creating the new
1224
- # generator in the database.
1225
- #
1226
- def Generator.create(name, connection)
1227
- end
1228
- end
1229
-
1230
-
1231
- #
1232
- # This class represents a connection to the service manager for a Firebird
1233
- # database server instance. NOTE: This class does not currently work on the
1234
- # Mac OS X platform.
1235
- #
1236
- class ServiceManager
1237
- #
1238
- # This is the constructor for the ServiceManager class.
1239
- #
1240
- # ==== Parameters
1241
- # host:: The name of the host supporting the service manager to be
1242
- # connected with.
1243
- #
1244
- def initialize(host)
1245
- end
1246
-
1247
-
1248
- #
1249
- # This method attaches a ServiceManager object to its host service. The
1250
- # user name used to connect with can affect which services can be accessed
1251
- # on the server.
1252
- #
1253
- # ==== Parameters
1254
- # user:: A string containing the user name to connect with.
1255
- # password:: A string containing the user password to connect with.
1256
- #
1257
- def connect(user, password)
1258
- end
1259
-
1260
-
1261
- #
1262
- # This method disconnects a previously connected ServiceManager object.
1263
- #
1264
- def disconnect
1265
- end
1266
-
1267
-
1268
- #
1269
- # This method is used to determine whether a ServiceManager object has
1270
- # been connected.
1271
- #
1272
- def connected?
1273
- end
1274
-
1275
-
1276
- #
1277
- # This method is used to batch execute a collection of task objects.
1278
- #
1279
- # ==== Parameters
1280
- # tasks:: One or more task objects to be executed by the service manager.
1281
- #
1282
- # ==== Exceptions
1283
- # FireRubyException:: Generated whenever this method is called on a
1284
- # disconnected service manager or is a problem
1285
- # occurs executing one of the tasks.
1286
- #
1287
- def execute(*tasks)
1288
- end
1289
- end
1290
-
1291
-
1292
- #
1293
- # This class represents a service manager task to add a new user to a
1294
- # database instance. NOTE: This class does not currently work on the
1295
- # Mac OS X platform.
1296
- #
1297
- class AddUser
1298
- # Attribute accessor.
1299
- attr_reader :user_name, :password, :first_name, :middle_name, :last_name
1300
-
1301
- # Attribute mutator.
1302
- attr_writer :user_name, :password, :first_name, :middle_name, :last_name
1303
-
1304
- #
1305
- # This is a constructor for the AddUser class.
1306
- #
1307
- # ==== Parameters
1308
- # user_name:: A String containing the user name to be assigned to the
1309
- # new user.
1310
- # password:: A String containing the password to be assigned to the
1311
- # new user.
1312
- # first_name:: A String containing the first name to be associated with
1313
- # the new user. Defaults to nil.
1314
- # middle_name:: A String containing the middle name to be associated
1315
- # with the new user. Defaults to nil.
1316
- # last_name:: A String containing the last name to be associated with
1317
- # the new user. Defaults to nil.
1318
- #
1319
- def initialize(user_name, password, firsts_name=nil, middle_name=nil,
1320
- last_name=nil)
1321
- end
1322
-
1323
-
1324
- #
1325
- # This method executes the add user task against a service manager.
1326
- #
1327
- # ==== Parameters
1328
- # manager:: A reference to the ServiceManager object to execute the task
1329
- # on.
1330
- #
1331
- # ==== Exceptions
1332
- # FireRubyException:: Generated whenever a disconnected service manager
1333
- # is specified or an error occurs executing the
1334
- # task.
1335
- #
1336
- def execute(manager)
1337
- end
1338
- end
1339
-
1340
-
1341
- #
1342
- # This class represents a service manager task to remove an existing user
1343
- # from a database instance. NOTE: This class does not currently work on the
1344
- # Mac OS X platform.
1345
- #
1346
- class RemoveUser
1347
- # Attribute accessor.
1348
- attr_reader :user_name
1349
-
1350
- # Attribute mutator.
1351
- attr_writer :user_name
1352
-
1353
- #
1354
- # This is a constructor for the RemoveUser class.
1355
- #
1356
- # ==== Parameters
1357
- # user_name:: A String containing the user name to be assigned to the
1358
- # new user.
1359
- #
1360
- def initialize(user_name)
1361
- end
1362
-
1363
-
1364
- #
1365
- # This method executes the remove user task against a service manager.
1366
- #
1367
- # ==== Parameters
1368
- # manager:: A reference to the ServiceManager object to execute the task
1369
- # on.
1370
- #
1371
- # ==== Exceptions
1372
- # FireRubyException:: Generated whenever a disconnected service manager
1373
- # is specified or an error occurs executing the
1374
- # task.
1375
- #
1376
- def execute(manager)
1377
- end
1378
- end
1379
-
1380
-
1381
- #
1382
- # This class represents a service manager task to backup an existing database
1383
- # on the Firebird server. NOTE: This class does not currently work on the
1384
- # Mac OS X platform.
1385
- #
1386
- class Backup
1387
- # Attribute accessor.
1388
- attr_reader :backup_file, :database
1389
-
1390
- # Attribute mutator.
1391
- attr_writer :backup_file, :database
1392
-
1393
- #
1394
- # This is the constructor for the Backup class.
1395
- #
1396
- # ==== Parameters
1397
- # database:: A String or File giving the path and name (relative to the
1398
- # database server) of the main database file for the database
1399
- # to be backed up.
1400
- # file:: A String or File giving the path and name (relative to the
1401
- # database server) of the back up file to be generated.
1402
- #
1403
- def initialize(database, file)
1404
- end
1405
-
1406
-
1407
- #
1408
- # This method fetches the blocking factor to be used in generating the
1409
- # back up. This will return nil until it has been explicitly set.
1410
- #
1411
- def blocking_factor
1412
- end
1413
-
1414
-
1415
- #
1416
- # This method sets the blocking factor to be used in generating the
1417
- # back up.
1418
- #
1419
- # ==== Parameters
1420
- # size:: A reference to an integer containing the new back up blocking
1421
- # factor setting.
1422
- #
1423
- def blocking_factor=(size)
1424
- end
1425
-
1426
-
1427
- #
1428
- # This method fetches the ignore checksums setting for a Backup object.
1429
- #
1430
- def ignore_checksums
1431
- end
1432
-
1433
-
1434
- #
1435
- # This method is used to set the indicator for whether checksum values
1436
- # should be ignored in performing a backup.
1437
- #
1438
- # ==== Parameters
1439
- # setting:: True to ignore checksums, false otherwise.
1440
- #
1441
- def ignore_checksums=(setting)
1442
- end
1443
-
1444
-
1445
- #
1446
- # This method fetches the ignore limbo setting for a Backup object.
1447
- #
1448
- def ignore_limbo
1449
- end
1450
-
1451
-
1452
- #
1453
- # This method is used to set the indicator for whether limbo transactions
1454
- # should be ignored in performing a backup.
1455
- #
1456
- # ==== Parameters
1457
- # setting:: True to ignore limbo transactions, false otherwise.
1458
- #
1459
- def ignore_limbo=(setting)
1460
- end
1461
-
1462
-
1463
- #
1464
- # This method fetches the metadata only setting for a Backup object.
1465
- #
1466
- def metadata_only
1467
- end
1468
-
1469
-
1470
- #
1471
- # This method is used to set the indicator for whether a backup stores
1472
- # only the database metadata.
1473
- #
1474
- # ==== Parameters
1475
- # setting:: True to store only metadata, false otherwise.
1476
- #
1477
- def metadata_only=(setting)
1478
- end
1479
-
1480
-
1481
- #
1482
- # This method fetches the garbage collect setting for a Backup object.
1483
- #
1484
- def garbage_collect
1485
- end
1486
-
1487
-
1488
- #
1489
- # This method is used to set the indicator for whether the backup will
1490
- # undertake garbage collection.
1491
- #
1492
- # ==== Parameters
1493
- # setting:: True to perform garbage collection, false otherwise.
1494
- #
1495
- def garbage_collect=(setting)
1496
- end
1497
-
1498
-
1499
- #
1500
- # This method fetches the non-transportable setting for a Backup object.
1501
- #
1502
- def non_transportable
1503
- end
1504
-
1505
-
1506
- #
1507
- # This method is used to set the indicator for whether backup generated
1508
- # by the task will be platform specific.
1509
- #
1510
- # ==== Parameters
1511
- # setting:: True to generate a platform specific backup, false otherwise.
1512
- #
1513
- def non_transportable=(setting)
1514
- end
1515
-
1516
-
1517
- #
1518
- # This method fetches the convert tables setting for a Backup object.
1519
- #
1520
- def convert_tables
1521
- end
1522
-
1523
-
1524
- #
1525
- # This method is used to set the indicator for whether external tables
1526
- # will be converted to internal tables as part of the backup.
1527
- #
1528
- # ==== Parameters
1529
- # setting:: True to convert external tables, false otherwise.
1530
- #
1531
- def convert_tables=(setting)
1532
- end
1533
-
1534
-
1535
- #
1536
- # This method is used to execute a backup task against a service manager.
1537
- #
1538
- # ==== Parameters
1539
- # manager:: A reference to the service manager to execute the backup
1540
- # task against.
1541
- #
1542
- # ==== Exceptions
1543
- # FireRubyException:: Generated whenever a disconnected service manager
1544
- # is specified or a problem occurs executing the
1545
- # task.
1546
- #
1547
- def execute(manager)
1548
- end
1549
-
1550
-
1551
- #
1552
- # This method fetches the log value for a Backup task. This value will
1553
- # always be nil until the task has been executed. After a successful
1554
- # execution the log value should contain output from the backup task
1555
- # generated on the server.
1556
- #
1557
- def log
1558
- end
1559
- end
1560
-
1561
-
1562
- #
1563
- # This class represents a service manager task to restore a previously
1564
- # created database backup on the Firebird server. NOTE: This class does not
1565
- # currently work on the Mac OS X platform.
1566
- #
1567
- class Restore
1568
- # Attribute accessor.
1569
- attr_reader :backup_file, :database
1570
-
1571
- # Attribute mutator.
1572
- attr_writer :backup_file, :database
1573
-
1574
- # Access mode constant definition.
1575
- ACCESS_READ_ONLY = 39
1576
-
1577
- # Access mode constant definition.
1578
- ACCESS_READ_WRITE = 40
1579
-
1580
- # Restore mode constant definition.
1581
- MODE_CREATE = 0x1000
1582
-
1583
- # Restore mode constant definition.
1584
- MODE_REPLACE = 0x2000
1585
-
1586
- #
1587
- # This is the constructor for the Restore class.
1588
- #
1589
- # ==== Parameters
1590
- # file:: A String or File containing the path and name (relative to
1591
- # the server) of the backup file to be used in the restore.
1592
- # database:: A String or File containing the path and name (relative to
1593
- # the server) of the database file to be restored.
1594
- #
1595
- def initialize(file, database)
1596
- end
1597
-
1598
-
1599
- #
1600
- # This method retrieves the cache buffers setting for a Restore object.
1601
- # This will be nil until a value is actual set.
1602
- #
1603
- def cache_buffers
1604
- end
1605
-
1606
-
1607
- #
1608
- # This method updates the cache buffers setting for a Restore object.
1609
- #
1610
- # ==== Parameters
1611
- # setting:: The new value for the object setting. Should be an integer.
1612
- #
1613
- def cache_buffers=(setting)
1614
- end
1615
-
1616
-
1617
- #
1618
- # This method retrieves the page size setting for a Restore object.
1619
- # This will be nil until a value is actual set.
1620
- #
1621
- def page_size
1622
- end
1623
-
1624
-
1625
- #
1626
- # This method updates the page size setting for a Restore object.
1627
- #
1628
- # ==== Parameters
1629
- # setting:: The new value for the object setting. Should be an integer.
1630
- #
1631
- def page_size=(setting)
1632
- end
1633
-
1634
-
1635
- #
1636
- # This method retrieves the access mode setting for a Restore object.
1637
- # This will be nil until a value is actual set.
1638
- #
1639
- def access_mode
1640
- end
1641
-
1642
-
1643
- #
1644
- # This method updates the access mode setting for a Restore object.
1645
- #
1646
- # ==== Parameters
1647
- # setting:: The new value for the object setting. This should be one
1648
- # of Restore::ACCESS_READ_ONLY or Restore::ACCESS_READ_WRITE.
1649
- #
1650
- def access_mode=(setting)
1651
- end
1652
-
1653
-
1654
- #
1655
- # This method retrieves the build indices setting for a Restore object.
1656
- #
1657
- def build_indices
1658
- end
1659
-
1660
-
1661
- #
1662
- # This method updates the build indices setting for a Restore object.
1663
- # This value affects whether the various indexes for a database are
1664
- # restored with the restore task.
1665
- #
1666
- # ==== Parameters
1667
- # setting:: True to rebuild the database indices, false otherwise.
1668
- #
1669
- def build_indices=(setting)
1670
- end
1671
-
1672
-
1673
- #
1674
- # This method retrieves the no shadows setting for a Restore object.
1675
- #
1676
- def no_shadows
1677
- end
1678
-
1679
-
1680
- #
1681
- # This method updates the no shadows setting for a Restore object.
1682
- # This value affects whether shadow databases are recreated as part of a
1683
- # restore.
1684
- #
1685
- # ==== Parameters
1686
- # setting:: True to recreate shadow files, false otherwise.
1687
- #
1688
- def no_shadows=(setting)
1689
- end
1690
-
1691
-
1692
- #
1693
- # This method retrieves the validity checks setting for a Restore object.
1694
- #
1695
- def check_validity
1696
- end
1697
-
1698
-
1699
- #
1700
- # This method updates the validity checks setting for a Restore object.
1701
- # This value affects whether the restore performs validity checks on the
1702
- # database as it is restored.
1703
- #
1704
- # ==== Parameters
1705
- # setting:: True to perform validity checks, false otherwise.
1706
- #
1707
- def check_validity=(setting)
1708
- end
1709
-
1710
-
1711
- #
1712
- # This method retrieves the commit tables setting for a Restore object.
1713
- #
1714
- def commit_tables
1715
- end
1716
-
1717
-
1718
- #
1719
- # This method updates the commit tables setting for a Restore object.
1720
- # This value affects whether the restore commits tables as they are
1721
- # restored.
1722
- #
1723
- # ==== Parameters
1724
- # setting:: True to commit tables as they are restored, false otherwise.
1725
- #
1726
- def commit_tables=(setting)
1727
- end
1728
-
1729
-
1730
- #
1731
- # This method retrieves the restore mode setting for a Restore object.
1732
- #
1733
- def restore_mode
1734
- end
1735
-
1736
-
1737
- #
1738
- # This method updates the restore mode setting for a Restore object.
1739
- # This value affects whether the restore will overwrite an existing
1740
- # database.
1741
- #
1742
- # ==== Parameters
1743
- # setting:: Either Restore::MODE_CREATE (default) or
1744
- # Restore::MODE_REPLACE.
1745
- #
1746
- def restore_mode=(setting)
1747
- end
1748
-
1749
-
1750
- #
1751
- # This method retrieves the use all space setting for a Restore object.
1752
- #
1753
- def use_all_space
1754
- end
1755
-
1756
-
1757
- #
1758
- # This method updates the use all space setting for a Restore object.
1759
- # This value affects whether restore leaves space within the database
1760
- # file for expansion. This can be switched on for read only databases.
1761
- #
1762
- # ==== Parameters
1763
- # setting:: True leave no default expansion space within the restored
1764
- # database file, false otherwise.
1765
- #
1766
- def use_all_space=(setting)
1767
- end
1768
-
1769
-
1770
- #
1771
- # This method is used to execute a restore task against a service manager.
1772
- #
1773
- # ==== Parameters
1774
- # manager:: A reference to the service manager to execute the restore
1775
- # task against.
1776
- #
1777
- # ==== Exceptions
1778
- # FireRubyException:: Generated whenever a disconnected service manager
1779
- # is specified or a problem occurs executing the
1780
- # task.
1781
- #
1782
- def execute(manager)
1783
- end
1784
-
1785
-
1786
- #
1787
- # This method fetches the log value for a Restore task. This value will
1788
- # always be nil until the task has been executed. After a successful
1789
- # execution the log value should contain output from the restore task
1790
- # generated on the server.
1791
- #
1792
- def log
1793
- end
1794
- end
1795
- end
1
+ #
2
+ # This file is a stand-in that allows for the generation of rdoc documentation
3
+ # for the FireRuby extension for the Ruby programming language. The extension
4
+ # is coded in C and documented with Doxygen comments, so this file is used to
5
+ # generate the native Ruby documentation instead.
6
+ #
7
+
8
+ #
9
+ # This module contains all of the classes and definitions relating to the
10
+ # FireRuby extension for the Ruby language.
11
+ #
12
+ module FireRuby
13
+ #
14
+ # This class provides the exception type used by the FireRuby library.
15
+ #
16
+ class FireRubyException
17
+ #
18
+ # This is the constructor for the FireRubyError class.
19
+ #
20
+ # ==== Parameters
21
+ # message:: A string containing the error message for the object.
22
+ #
23
+ def initialize(message)
24
+ end
25
+
26
+
27
+ #
28
+ # This is the accessor for the error message attribute
29
+ #
30
+ def message
31
+ end
32
+
33
+
34
+ #
35
+ # This is the accessor for the SQL code attribute.
36
+ #
37
+ def sql_code
38
+ end
39
+
40
+
41
+ #
42
+ # This is the accessor for the database code attribute.
43
+ #
44
+ def db_code
45
+ end
46
+
47
+
48
+ #
49
+ # This function generates a simple description string for a FireRubyError
50
+ # object.
51
+ #
52
+ def to_s
53
+ end
54
+ end
55
+
56
+
57
+ #
58
+ # This class represents an existing database that can be connected to. It
59
+ # also provides functionality to allow for the creation of new databases.
60
+ #
61
+ class Database
62
+ #
63
+ # This is the constructor for the Database class.
64
+ #
65
+ # ==== Parameters
66
+ # file:: A string containing the database file specifier. This can
67
+ # include details for a remote server if needed.
68
+ # set:: A string containing the name of the character set to be
69
+ # used with the database. Defaults to nil.
70
+ #
71
+ def initialize(file, set=nil)
72
+ end
73
+
74
+
75
+ #
76
+ # This is the accessor for the database file specification attribute.
77
+ #
78
+ def file
79
+ end
80
+
81
+
82
+ #
83
+ # This method attempts to establish a connection to a database. If
84
+ # successful then a Connection instance is returned. If a block is
85
+ # provided to the method then the connection is closed after the
86
+ # block completes. If a block is specified the connection is provided
87
+ # as a parameter to the block.
88
+ #
89
+ # ==== Parameters
90
+ # user:: The user name to be used in making the connection. This
91
+ # defaults to nil.
92
+ # password:: The password to be used in making the connection. This
93
+ # defaults to nil.
94
+ # options:: A Hash of connection options. This should be made up of
95
+ # key/setting pairs where the keys are from the list that
96
+ # is defined within the Connection class. The settings are
97
+ # particular to the key, see the documentation for the
98
+ # Connection class for more details.
99
+ #
100
+ # ==== Exceptions
101
+ # Exception:: Thrown whenever a problem occurs connecting with the
102
+ # database.
103
+ #
104
+ def connect(user=nil, password=nil, options=nil)
105
+ yield(connection)
106
+ end
107
+
108
+
109
+ #
110
+ # This method attempts to drop the database referred to by the details
111
+ # in a Database object.
112
+ #
113
+ # ==== Parameters
114
+ # user:: The user name to be used in dropping the database.
115
+ # password:: The password to be used in dropping the database.
116
+ #
117
+ # ==== Exceptions
118
+ # FireRubyError:: Thrown whenever a problem occurs dropping the database
119
+ # instance.
120
+ #
121
+ def drop(user, password)
122
+ end
123
+
124
+
125
+ #
126
+ # This method can be used to programmatically created a database file.
127
+ # If successful this method returns a Database object.
128
+ #
129
+ # ==== Parameters
130
+ # file:: A string containing the path and name of the database file
131
+ # to be created.
132
+ # user:: A string containing the user name that will be used in
133
+ # creating the file.
134
+ # password:: A string containing the user password that will be used in
135
+ # creating the file.
136
+ # size:: The page size setting to be used with the new database file.
137
+ # This should be 1024, 2048, 4096 or 8192. Defaults to 1024.
138
+ # set:: The name of the default character set to be assigned to the
139
+ # new database file. If this parameter is specifed then the
140
+ # Database object created by the call will use it to whenever
141
+ # a connection request is made. Defaults to nil.
142
+ #
143
+ # ==== Exceptions
144
+ # Exception:: Generated whenever an invalid parameter is specified or a
145
+ # problem occurs creating the database file.
146
+ #
147
+ def Database.create(file, user, password, size=1024, set=nil)
148
+ end
149
+
150
+
151
+ #
152
+ # This method fetches the name of the character set currently assigned
153
+ # to a Database object. This can return nil to indicate that a explicit
154
+ # character set has not been assigned.
155
+ #
156
+ def character_set
157
+ end
158
+
159
+
160
+ #
161
+ # This method allows the specification of a database character set that
162
+ # will be used when creating connections to a database. The value set by
163
+ # this method can be overridden by providing an alternative in the connect
164
+ # call. To remove a character set specification from a Database object
165
+ # pass nil to this method.
166
+ #
167
+ # ==== Parameters
168
+ # set:: A string containing the name of the database character set.
169
+ #
170
+ def character_set=(set)
171
+ end
172
+ end
173
+
174
+
175
+ #
176
+ # This class represents a connection with a Firebird database.
177
+ #
178
+ class Connection
179
+ # A definition for a connection option. This option should be given a
180
+ # setting of either true or false.
181
+ MARK_DATABASE_DAMAGED = 17
182
+
183
+
184
+ # A definition for a connection option. This option should be given a
185
+ # setting of Connection::WRITE_ASYNCHRONOUS or
186
+ # Connection::WRITE_SYNCHRONOUS
187
+ WRITE_POLICY = 24
188
+
189
+
190
+ # A definition for a connection option. This option should be given a
191
+ # string setting which should be the name of the character set to be
192
+ # used by the connection.
193
+ CHARACTER_SET = 48
194
+
195
+
196
+ # A definition for a connection option. This option should be given a
197
+ # string setting which should be the name of the message file to be used
198
+ # by the connection.
199
+ MESSAGE_FILE = 47
200
+
201
+
202
+ # A definition for a connection option. This option should be given a
203
+ # an integer setting. Values between 1 and 255 are valid, with 75 being
204
+ # the default.
205
+ NUMBER_OF_CACHE_BUFFERS = 5
206
+
207
+
208
+ # A definition for a connection option. This option should be given a
209
+ # string value which should be the database DBA user name.
210
+ DBA_USER_NAME = 19
211
+
212
+
213
+ # A definition for a possible setting to accompany the WRITE_POLICY
214
+ # connection setting.
215
+ WRITE_ASYNCHONOUS = 0
216
+
217
+
218
+ # A definition for a possible setting to accompany the WRITE_POLICY
219
+ # connection setting.
220
+ WRITE_SYNCHONOUS = 1
221
+
222
+
223
+ #
224
+ # This is the constructor for the Connection class.
225
+ #
226
+ # ==== Parameters
227
+ # database:: A reference to the Database object to be connected to.
228
+ # user:: A reference to the user name to be used in making the
229
+ # database connection. Defaults to nil.
230
+ # password:: A reference to the user password to be used in making the
231
+ # connection. Defaults to nil.
232
+ # options:: A Hash containing the options to be applied to the new
233
+ # connection. The hash will contain key/setting values, with
234
+ # the keys being based on the option constants defined within
235
+ # the Connection class. Individual options have differing
236
+ # value requirements. See the option documentation entries
237
+ # for further details. Defaults to nil.
238
+ #
239
+ # ==== Exceptions
240
+ # Exception:: Generated whenever an invalid database is specified to
241
+ # the method or an issue occurs establishing the database
242
+ # connection.
243
+ #
244
+ def initialize(database, user, password, options)
245
+ end
246
+
247
+
248
+ #
249
+ # This method is used to determine whether a Connection object represents
250
+ # an active database connection.
251
+ #
252
+ def open?
253
+ end
254
+
255
+
256
+ #
257
+ # This method is used to determine whether a Connection object represents
258
+ # an inactive database connection.
259
+ #
260
+ def closed?
261
+ end
262
+
263
+
264
+ #
265
+ # This method detaches a Connection object from a database. The object
266
+ # may not be used for database functionality following a successful call
267
+ # to this method. The close method will fail if there are outstanding
268
+ # transactions for a connection.
269
+ #
270
+ # ==== Exceptions
271
+ # Exception:: Generated whenever the connection has at least one open
272
+ # transaction or an error occurs closing the connection.
273
+ #
274
+ def close
275
+ end
276
+
277
+
278
+ #
279
+ # This is the accessor method for the database attribute.
280
+ #
281
+ def database
282
+ end
283
+
284
+
285
+ #
286
+ # This method retrieves the user name that was used in creating a
287
+ # Connection object.
288
+ #
289
+ def user
290
+ end
291
+
292
+
293
+ #
294
+ # This method generates a simple descriptive string for a Connection
295
+ # object.
296
+ #
297
+ def to_s
298
+ end
299
+
300
+
301
+ #
302
+ # This method starts a new transaction against a connection. A successful
303
+ # call to this method returns a Transaction object. The transaction that
304
+ # is started relates to the Connection it was called upon only. To start
305
+ # a transaction that covers multiple connections use the Transaction
306
+ # class. This method accepts a block, taking a single parameter which
307
+ # will be the transaction created. This transaction is committed if the
308
+ # block completes normally or rolls back if an exception is thrown from
309
+ # the block.
310
+ #
311
+ # ==== Exceptions
312
+ # Exception:: Thrown whenever a problem occurs starting the transaction.
313
+ #
314
+ def start_transaction
315
+ yield transaction
316
+ end
317
+
318
+
319
+ #
320
+ # This function executes a SQL statement against a connection. If the
321
+ # statement represented a SQL query then a ResultSet object is returned.
322
+ # If the statement was a non-query SQL statement then an Integer is
323
+ # returned indicating the number of rows affected by the statement. For
324
+ # all other types of statement the method returns nil. The method also
325
+ # accepts a block that takes a single parameter. This block will be
326
+ # executed once for each row in any result set generated.
327
+ #
328
+ # ==== Parameters
329
+ # sql:: The SQL statement to be executed.
330
+ # transaction:: The transaction to execute the SQL statement within.
331
+ #
332
+ # ==== Exceptions
333
+ # Exception:: Generated if an error occurs executing the SQL statement.
334
+ #
335
+ def execute(sql, transaction)
336
+ yield(row)
337
+ end
338
+
339
+
340
+ #
341
+ # This function executes a SQL statement against a connection. This
342
+ # differs from the execute method in that an anonymous transaction is
343
+ # used in executing the statement. The output from this method is the
344
+ # same as for the execute method. The method also accepts a block that
345
+ # takes a single parameter. This block will be executed once for each
346
+ # row in any result set generated.
347
+ #
348
+ # ==== Parameters
349
+ # sql:: The SQL statement to be executed.
350
+ #
351
+ # ==== Exceptions
352
+ # Exception:: Generated whenever a problem occurs executing the SQL
353
+ # statement.
354
+ #
355
+ def execute_immediate(sql)
356
+ yield(row)
357
+ end
358
+ end
359
+
360
+
361
+ #
362
+ # This class represents a Firebird database transaction. There may be
363
+ # multiple transaction outstanding against a connection at any one time.
364
+ #
365
+ class Transaction
366
+ TPB_VERSION_1 = 1
367
+ TPB_VERSION_3 = 3
368
+ TPB_CONSISTENCY = 1
369
+ TPB_CONCURRENCY = 2
370
+ TPB_SHARED = 3
371
+ TPB_PROTECTED = 4
372
+ TPB_EXCLUSIVE = 5
373
+ TPB_WAIT = 6
374
+ TPB_NO_WAIT = 7
375
+ TPB_READ = 8
376
+ TPB_WRITE = 9
377
+ TPB_LOCK_READ = 10
378
+ TPB_LOCK_WRITE = 11
379
+ TPB_VERB_TIME = 12
380
+ TPB_COMMIT_TIME = 13
381
+ TPB_IGNORE_LIMBO = 14
382
+ TPB_READ_COMMITTED = 15
383
+ TPB_AUTO_COMMIT = 16
384
+ TPB_REC_VERSION = 17
385
+ TPB_NO_REC_VERSION = 18
386
+ TPB_RESTART_REQUESTS = 19
387
+ # Transaction parameter buffer value constants.
388
+ TPB_NO_AUTO_UNDO = 20
389
+
390
+
391
+ #
392
+ # This is the constructor for the Transaction class.
393
+ #
394
+ # ==== Parameters
395
+ # connections:: Either a single instance of the Connection class or
396
+ # an array of Connection instances to specify a
397
+ # multi-database transaction.
398
+ #
399
+ # ==== Exceptions
400
+ # Exception:: Generated whenever the method is passed an invalid
401
+ # parameter or a problem occurs creating the transaction.
402
+ #
403
+ def initialize(connections)
404
+ end
405
+
406
+
407
+ #
408
+ # This method is used to determine whether a Transaction object is still
409
+ # valid for use (i.e. commit or rollback has not been called for the
410
+ # Transaction).
411
+ #
412
+ def active?
413
+ end
414
+
415
+
416
+ #
417
+ # This is the accessor for the connections attribute. This method returns
418
+ # an array of the connections that the transaction applies to.
419
+ #
420
+ def connections
421
+ end
422
+
423
+
424
+ #
425
+ # This method is used to determine whether a given Transaction applies to
426
+ # a specified Connection.
427
+ #
428
+ # ==== Parameters
429
+ # connection:: A reference to the Connection object to perform the test
430
+ # for.
431
+ #
432
+ def for_connection?(connection)
433
+ end
434
+
435
+
436
+ #
437
+ # This method commits the details outstanding against a Transaction
438
+ # object. The Transaction object may not be reused after a successful
439
+ # call to this method.
440
+ #
441
+ # ==== Exceptions
442
+ # Exception:: Generated whenever a problem occurs committing the details
443
+ # of the transaction.
444
+ #
445
+ def commit
446
+ end
447
+
448
+
449
+ #
450
+ # This method rolls back the details outstanding against a Transaction
451
+ # object. The Transaction object may not be reused after a successful
452
+ # call to this method.
453
+ #
454
+ # ==== Exceptions
455
+ # Exception:: Generated whenever a problem occurs rolling back the
456
+ # details of the transaction.
457
+ #
458
+ def rollback
459
+ end
460
+
461
+
462
+ #
463
+ # This method executes a SQL statement using a Transaction object. This
464
+ # method will only work whenever a Transaction object applies to a
465
+ # single Connection as it would otherwise be impossible to determine
466
+ # which connection to execute against. If the statement executed was a
467
+ # SQL query then the method returns a ResultSet object. For non-query SQL
468
+ # statements (insert, update or delete) the method returns an Integer that
469
+ # contains the number of rows affected by the statement. For all other
470
+ # statements the method returns nil. The method also accepts a block that
471
+ # takes a single parameter. If the SQL statement was a query the block
472
+ # will be invoked and passed each row retrieved.
473
+ #
474
+ # ==== Parameters
475
+ # sql:: A string containing the SQL statement to be executed.
476
+ #
477
+ # ==== Exceptions
478
+ # Exception:: Generated whenever the Transaction object represents more
479
+ # than one connection or a problem occurs executing the SQL
480
+ # statement.
481
+ #
482
+ def execute(sql)
483
+ yield(row)
484
+ end
485
+
486
+
487
+ #
488
+ # This method allows for the creation of a Transaction object with
489
+ # non-standard settings.
490
+ #
491
+ # ==== Parameters
492
+ # connections:: Either a single Connection object or an array of
493
+ # Connection objects that the new Transaction will
494
+ # be associated with.
495
+ # parameters:: An array of the parameters to be used in creating
496
+ # the new constants. Populate this from the TPB
497
+ # constants defined within the class.
498
+ #
499
+ # ==== Exceptions
500
+ # FireRubyError:: Generated whenever a problem occurs creating the
501
+ # transaction.
502
+ #
503
+ def Transaction.create(connections, parameters)
504
+ end
505
+ end
506
+
507
+
508
+ #
509
+ # This class represents a prepared SQL statement that may be executed more
510
+ # than once.
511
+ #
512
+ class Statement
513
+ # A definition for a SQL statement type constant.
514
+ SELECT_STATEMENT = 1
515
+
516
+ # A definition for a SQL statement type constant.
517
+ INSERT_STATEMENT = 2
518
+
519
+ # A definition for a SQL statement type constant.
520
+ UPDATE_STATEMENT = 3
521
+
522
+ # A definition for a SQL statement type constant.
523
+ DELETE_STATEMENT = 4
524
+
525
+ # A definition for a SQL statement type constant.
526
+ DDL_STATEMENT = 5
527
+
528
+ # A definition for a SQL statement type constant.
529
+ GET_SEGMENT_STATEMENT = 6
530
+
531
+ # A definition for a SQL statement type constant.
532
+ PUT_SEGMENT_STATEMENT = 7
533
+
534
+ # A definition for a SQL statement type constant.
535
+ EXECUTE_PROCEDURE_STATEMENT = 8
536
+
537
+ # A definition for a SQL statement type constant.
538
+ START_TRANSACTION_STATEMENT = 9
539
+
540
+ # A definition for a SQL statement type constant.
541
+ COMMIT_STATEMENT = 10
542
+
543
+ # A definition for a SQL statement type constant.
544
+ ROLLBACK_STATEMENT = 11
545
+
546
+ # A definition for a SQL statement type constant.
547
+ SELECT_FOR_UPDATE_STATEMENT = 12
548
+
549
+ # A definition for a SQL statement type constant.
550
+ SET_GENERATOR_STATEMENT = 13
551
+
552
+ # A definition for a SQL statement type constant.
553
+ SAVE_POINT_STATEMENT = 14
554
+
555
+ #
556
+ # This is the constructor for the Statement class.
557
+ #
558
+ # ==== Parameters
559
+ # connection:: The Connection object that the SQL statement will be
560
+ # executed through.
561
+ # transaction:: The Transaction object that the SQL statement will be
562
+ # executed under.
563
+ # sql:: The SQL statement to be prepared for execution.
564
+ # dialect:: The Firebird dialect to be used in preparing the SQL
565
+ # statement.
566
+ #
567
+ def initialize(connection, transaction, sql, dialect)
568
+ end
569
+
570
+
571
+ #
572
+ # This is the accessor for the connection attribute.
573
+ #
574
+ def connection
575
+ end
576
+
577
+
578
+ #
579
+ # This is the accessor for the transaction attribute.
580
+ #
581
+ def transaction
582
+ end
583
+
584
+
585
+ #
586
+ # This is the accessor for the SQL statement attribute.
587
+ #
588
+ def sql
589
+ end
590
+
591
+
592
+ #
593
+ # This is the accessor for the dialect attribute.
594
+ #
595
+ def dialect
596
+ end
597
+
598
+
599
+ #
600
+ # This method is used to determine the type of a SQL statement. The method
601
+ # will return one of the constant SQL types defined within the class.
602
+ #
603
+ def type
604
+ end
605
+
606
+
607
+ #
608
+ # This method fetches a count of the number of dynamic parameters for
609
+ # a statement object (i.e. the number of parameters that must be provided
610
+ # with values before the SQL statement can be executed).
611
+ #
612
+ def parameter_count
613
+ end
614
+
615
+
616
+ #
617
+ # This method executes the SQL statement within a Statement object. This
618
+ # method returns a ResultSet object if the statement executed was a SQL
619
+ # query. For non-query SQL statements (insert, update or delete) it
620
+ # returns an Integer indicating the number of affected rows. For all other
621
+ # statements the method returns nil. This method accepts a block taking a
622
+ # single parameter. If this block is provided and the statement is a query
623
+ # then the rows returned by the query will be passed, one at a time, to
624
+ # the block.
625
+ #
626
+ # ==== Exception
627
+ # Exception:: Generated if the Statement object actual requires some
628
+ # parameters or a problem occurs executing the SQL statement.
629
+ #
630
+ def execute
631
+ yield row
632
+ end
633
+
634
+
635
+ #
636
+ # This method executes the SQL statement within a Statement object and
637
+ # passes it a set of parameters. Parameterized statements use question
638
+ # marks as place holders for values that may change between calls to
639
+ # execute the statement. This method returns a ResultSet object if the
640
+ # statement executed was a SQL query. If the statement was a non-query SQL
641
+ # statement (insert, update or delete) then the method returns a count of
642
+ # the number of rows affected. For all other types of statement the method
643
+ # returns nil. This method accepts a block taking a single parameter. If
644
+ # this block is provided and the statement is a query then the rows
645
+ # returned by the query will be passed, one at a time, to the block.
646
+ #
647
+ # ==== Parameters
648
+ # parameters:: An array of the parameters for the statement. An effort
649
+ # will be made to convert the values passed in to the
650
+ # appropriate types but no guarantees are made (especially
651
+ # in the case of text fields, which will simply use to_s
652
+ # if the object passed is not a String).
653
+ #
654
+ # ==== Exception
655
+ # Exception:: Generated whenever a problem occurs translating one of the
656
+ # input parameters or executing the SQL statement.
657
+ #
658
+ def execute_for(parameters)
659
+ yield row
660
+ end
661
+
662
+
663
+ #
664
+ # This method releases the database resources associated with a Statement
665
+ # object and should be explicitly called when a Statement object is of
666
+ # no further use.
667
+ #
668
+ # ==== Exceptions
669
+ # FireRubyError:: Generated whenever a problem occurs closing the
670
+ # statement object.
671
+ #
672
+ def close
673
+ end
674
+ end
675
+
676
+
677
+ #
678
+ # This class represents the results of a SQL query executed against a
679
+ # database. The viable lifespan of a ResultSet object is limited by the
680
+ # transaction that was used in it's creation. Once this transaction has
681
+ # been committed or rolled back all related ResultSet object are invalidated
682
+ # and can no longer be used.
683
+ #
684
+ class ResultSet
685
+ include Enumerable
686
+
687
+ #
688
+ # This is the constructor for the ResultSet object.
689
+ #
690
+ # ==== Parameters
691
+ # connection:: A reference to the Connection object that will be used
692
+ # to execute the SQL query.
693
+ # transaction:: A reference to the Transaction object that will be used
694
+ # in executing the SQL query.
695
+ # sql:: A reference to a String containing the SQL query that
696
+ # will be executed.
697
+ # dialect:: A reference to an integer containing the Firebird dialect
698
+ # to be used in executing the SQL statement.
699
+ #
700
+ # ==== Exceptions
701
+ # FireRubyException:: Generated whenever a non-query SQL statement is
702
+ # specified, an invalid connection or transaction is
703
+ # provided or a problem occurs executing the SQL
704
+ # against the database.
705
+ #
706
+ def initialize(connection, transaction, sql, dialect)
707
+ end
708
+
709
+
710
+ #
711
+ # This is the accessor for the connection attribute.
712
+ #
713
+ def connection
714
+ end
715
+
716
+
717
+ #
718
+ # This is the accessor for the transaction attribute.
719
+ #
720
+ def transaction
721
+ end
722
+
723
+
724
+ #
725
+ # This is the accessor for the sql attribute.
726
+ #
727
+ def sql
728
+ end
729
+
730
+
731
+ #
732
+ # This is the accessor for the dialect attribute.
733
+ #
734
+ def dialect
735
+ end
736
+
737
+
738
+ #
739
+ # This method fetches a count of the number of columns in a row of data
740
+ # that the ResultSet can fetch.
741
+ #
742
+ def column_count
743
+ end
744
+
745
+
746
+ #
747
+ # This method fetches the name associated with a specified column for a
748
+ # ResultSet object.
749
+ #
750
+ # ==== Parameters
751
+ # column:: A reference to the column number to fetch the details for.
752
+ # Column numbers start at zero.
753
+ #
754
+ def column_name(column)
755
+ end
756
+
757
+
758
+ #
759
+ # This method fetches the alias associated with a specified column for a
760
+ # ResultSet object.
761
+ #
762
+ # ==== Parameters
763
+ # column:: A reference to the column number to fetch the details for.
764
+ # Column numbers start at zero.
765
+ #
766
+ def column_alias(column)
767
+ end
768
+
769
+
770
+ #
771
+ # This method fetches the table name associated with a specified column
772
+ # for a ResultSet object.
773
+ #
774
+ # ==== Parameters
775
+ # column:: A reference to the column number to fetch the details for.
776
+ # Column numbers start at zero.
777
+ #
778
+ def column_table(column)
779
+ end
780
+
781
+
782
+ #
783
+ # This method fetches a single rows worth of data from the ResultSet
784
+ # object. If the set contains more rows then an array containing the
785
+ # row data will be retrieved. If the ResultSet is exhausted (i.e. all
786
+ # rows have been fetched) then nil is returned. Translation of the row
787
+ # data into an appropriate Ruby type is performed on the row data that
788
+ # is extracted.
789
+ #
790
+ def fetch
791
+ end
792
+
793
+
794
+ #
795
+ # This method is used to determine if all of the rows have been retrieved
796
+ # from a ResultSet object. This method will always return false until
797
+ # the fetch method has been called at least once so it cannot be used to
798
+ # detect a result set that returns no rows.
799
+ #
800
+ def exhausted?
801
+ end
802
+
803
+
804
+ #
805
+ # This method fetches a count of the total number of rows retrieved
806
+ # from a result set.
807
+ #
808
+ def row_count
809
+ end
810
+
811
+
812
+ #
813
+ # This method provides an iterator for the (remaining) rows contained in
814
+ # a ResultSet object.
815
+ #
816
+ # ==== Parameters
817
+ # block:: A block that takes a single parameter. This will be called for
818
+ # and passed each remaining row (as per the fetch method) from
819
+ # the ResultSet.
820
+ #
821
+ def each(&block)
822
+ end
823
+
824
+
825
+ #
826
+ # This method releases the database resources associated with a ResultSet
827
+ # object and should be explicitly called when a ResultSet object is of
828
+ # no further use. The method is implicitly called if the rows available
829
+ # from a ResultSet are exhausted but calling this method at that time
830
+ # will not cause an error.
831
+ #
832
+ # ==== Exceptions
833
+ # FireRubyError:: Generated whenever a problem occurs closing the result
834
+ # set object.
835
+ #
836
+ def close
837
+ end
838
+
839
+ #
840
+ # This method retrieves the base SQL type for a column of data within a
841
+ # ResultSet object. The method returns one of the base types defined in
842
+ # the SQLType class but does not return an actual SQLType object.
843
+ #
844
+ # ==== Parameters
845
+ # index:: The offset from the ResultSet first column of the column to
846
+ # return the type information for.
847
+ #
848
+ def get_base_type(index)
849
+ end
850
+ end
851
+
852
+
853
+ #
854
+ # This class models a row of data fetched as part of a SQL query.
855
+ #
856
+ class Row
857
+ include Enumerable
858
+
859
+ #
860
+ # This is the constructor for the Row class. This method shouldn't really
861
+ # be used as Row objects are automatically created by ResultSets.
862
+ #
863
+ # ==== Parameters
864
+ # results:: The ResultSet object that the row relates to.
865
+ # data:: An array containing the row data values.
866
+ # number:: The row number for the new row.
867
+ #
868
+ def initialize(results, data, number)
869
+ end
870
+
871
+ #
872
+ # This is the accessor for the row number attribute. This will generally
873
+ # reflect the order the row was fetched from the result set in, with 1
874
+ # being the first row retrieved.
875
+ #
876
+ def number
877
+ end
878
+
879
+
880
+ #
881
+ # This method fetches a count of the number of columns of data that are
882
+ # available from a row.
883
+ #
884
+ def column_count
885
+ end
886
+
887
+
888
+ #
889
+ # This method fetches the name of a column within a row of data.
890
+ #
891
+ # ==== Parameters
892
+ # index:: The index of the column to fetch the name for. The first
893
+ # column in the row is at offset zero.
894
+ #
895
+ def column_name(index)
896
+ end
897
+
898
+
899
+ #
900
+ # This method fetches the alias of a column within a row of data.
901
+ #
902
+ # ==== Parameters
903
+ # index:: The index of the column to fetch the alias for. The first
904
+ # column in the row is at offset zero.
905
+ #
906
+ def column_alias(index)
907
+ end
908
+
909
+
910
+ #
911
+ # This method fetches the value associated with a column within a Row
912
+ # object.
913
+ #
914
+ # ==== Parameters
915
+ # index:: Either the offset of the column to retrieve the value of or
916
+ # the alias of the column to retrieve the value of (column alias
917
+ # comparisons are case sensitive).
918
+ #
919
+ def [](index)
920
+ end
921
+
922
+
923
+ #
924
+ # This method iterates over the contents of a Row object. The block
925
+ # specified for the method should accept two parameters; one for the
926
+ # column alias and one for the column value.
927
+ #
928
+ def each
929
+ yield column, vlaue
930
+ end
931
+
932
+
933
+ #
934
+ # This method iterates over the column names for a Row class.
935
+ #
936
+ def each_key
937
+ yield column
938
+ end
939
+
940
+
941
+ #
942
+ # This method iterators over the column values for a Row class.
943
+ #
944
+ def each_value
945
+ yield value
946
+ end
947
+
948
+
949
+ #
950
+ # An implementation of the Hash#fetch method for the Row class. The
951
+ # method accepts a block but this should not be specified if a value
952
+ # for the alternative parameter is specified.
953
+ #
954
+ # ==== Parameters
955
+ # key:: A string containing the column alias to retrieve.
956
+ # alternative:: A reference to the alternative value to be returned if
957
+ # the keyed value is not found. Defaults to nil.
958
+ #
959
+ def fetch(key, alternative=nil)
960
+ yield key
961
+ end
962
+
963
+
964
+ #
965
+ # This method is used to determine whether a Row object contains a given
966
+ # column alias.
967
+ #
968
+ # ==== Parameters
969
+ # name:: A String containing the column name to check for.
970
+ #
971
+ def has_key?(name)
972
+ end
973
+
974
+
975
+ #
976
+ # This method is used to determine whether a Row object contains a given
977
+ # column name.
978
+ #
979
+ # ==== Parameters
980
+ # name:: A String containing the column name to check for.
981
+ #
982
+ def has_column?(name)
983
+ end
984
+
985
+
986
+ #
987
+ # This method is used to determine whether a Row object contains a given
988
+ # column alias.
989
+ #
990
+ # ==== Parameters
991
+ # name:: A String containing the column alias to check for.
992
+ #
993
+ def has_alias?(name)
994
+ end
995
+
996
+
997
+ #
998
+ # This method is used to determine whether a Row object contains a given
999
+ # column value.
1000
+ #
1001
+ # ==== Parameters
1002
+ # value:: A reference to an object value to be checked for.
1003
+ #
1004
+ def has_value?(value)
1005
+ end
1006
+
1007
+
1008
+ #
1009
+ # This method retrieves an array of column aliases for a Row object.
1010
+ #
1011
+ def keys
1012
+ end
1013
+
1014
+
1015
+ #
1016
+ # This method retrieves an array of column names for a Row object.
1017
+ #
1018
+ def names
1019
+ end
1020
+
1021
+
1022
+ #
1023
+ # This method retrieves an array of column aliases for a Row object.
1024
+ #
1025
+ def aliases
1026
+ end
1027
+
1028
+
1029
+ #
1030
+ # This method retrieves an array of column values for a Row object.
1031
+ #
1032
+ def values
1033
+ end
1034
+
1035
+
1036
+ #
1037
+ # This method returns an array of the Row elements for which the specified
1038
+ # block returns true.
1039
+ #
1040
+ def select
1041
+ yield column, value
1042
+ end
1043
+
1044
+
1045
+ #
1046
+ # This method retrieves an Array containing the values from a Row object.
1047
+ # Each value is represented as an Array containing a column name and the
1048
+ # associated column value.
1049
+ #
1050
+ def to_a
1051
+ end
1052
+
1053
+
1054
+ #
1055
+ # This method retrieves a Hash created from a Row objects values. The Row
1056
+ # objects column names will be used as a key on to the column values.
1057
+ #
1058
+ def to_hash
1059
+ end
1060
+
1061
+
1062
+ #
1063
+ # This method returns an array of column values based on a list of column
1064
+ # aliases.
1065
+ #
1066
+ # ==== Parameters
1067
+ # names:: One or more Strings containing the names of the columns to
1068
+ # retrieve values for.
1069
+ #
1070
+ def values_at(*names)
1071
+ end
1072
+
1073
+ #
1074
+ # This method retrieves the base SQL type for a column of data within a
1075
+ # Row object. The method returns one of the base types defined in the
1076
+ # SQLType class but does not return an actual SQLType object.
1077
+ #
1078
+ # ==== Parameters
1079
+ # index:: The offset from the Row first column of the column to return
1080
+ # the type information for.
1081
+ #
1082
+ def get_base_type(index)
1083
+ end
1084
+ end
1085
+
1086
+ #
1087
+ # This class represents Blob data fetched from the database. The class defers
1088
+ # the actual loading of the blob until requested. The class is somewhat basic
1089
+ # and maybe expanded upon in later releases.
1090
+ #
1091
+ class Blob
1092
+ #
1093
+ # This is the constructor for the Blob class. This shouldn't really be
1094
+ # used outside of the FireRuby library.
1095
+ #
1096
+ def initialize
1097
+ end
1098
+
1099
+
1100
+ #
1101
+ # This method loads the entire data set for a blob as a string.
1102
+ #
1103
+ def to_s
1104
+ end
1105
+
1106
+
1107
+ #
1108
+ # This method closes a blob, freeing any resources associated with it.
1109
+ #
1110
+ def close
1111
+ end
1112
+
1113
+
1114
+ #
1115
+ # This method loads the segments of a blob one after another. The blob
1116
+ # segments are passed as strings to the block passed to the method.
1117
+ #
1118
+ def each
1119
+ yield segment
1120
+ end
1121
+ end
1122
+
1123
+
1124
+ #
1125
+ # This class represents a Firebird generator entity.
1126
+ #
1127
+ class Generator
1128
+ #
1129
+ # This is the constructor for the Generator class. Note, this method
1130
+ # assumes that the named generator already exists. If it doesn't then
1131
+ # the object will be constructed but will fail during use.
1132
+ #
1133
+ # ==== Parameters
1134
+ # name:: A string containing the generator name.
1135
+ # connection:: A reference to the Connection object that will be used
1136
+ # to access the generator.
1137
+ #
1138
+ def initialize(name, connection)
1139
+ end
1140
+
1141
+
1142
+ #
1143
+ # This is the accessor for the name attribute.
1144
+ #
1145
+ def name
1146
+ end
1147
+
1148
+
1149
+ #
1150
+ # This is the accessor for the connection attribute.
1151
+ #
1152
+ def connection
1153
+ end
1154
+
1155
+
1156
+ #
1157
+ # This method fetches the last value generator from a generator.
1158
+ #
1159
+ # ==== Exceptions
1160
+ # Exception:: Generated whenever a problem occurs accessing the
1161
+ # database generator.
1162
+ #
1163
+ def last
1164
+ end
1165
+
1166
+
1167
+ #
1168
+ # This method drops a generator from the database. After a successful
1169
+ # call to this method the Generator object may not be used to obtain
1170
+ # values unless it is recreated.
1171
+ #
1172
+ # ==== Exceptions
1173
+ # Exception:: Generated whenever a problem occurs dropping the generator
1174
+ # from the database.
1175
+ #
1176
+ def drop
1177
+ end
1178
+
1179
+
1180
+ #
1181
+ # This method fetches the next value, depending on a specified increment,
1182
+ # from a generator.
1183
+ #
1184
+ # ==== Parameters
1185
+ # step:: The step interval to be applied to the generator to obtain the
1186
+ # next value.
1187
+ #
1188
+ # ==== Exceptions
1189
+ # Exception:: Generated whenever a problem occurs accessing the
1190
+ # database generator.
1191
+ #
1192
+ def next(step)
1193
+ end
1194
+
1195
+
1196
+ #
1197
+ # This method is used to determine whether a named generator exists
1198
+ # within a database.
1199
+ #
1200
+ # ==== Parameters
1201
+ # name:: A string containing the generator name to check for.
1202
+ # connection:: A reference to the Connection object to be used in
1203
+ # performing the check.
1204
+ #
1205
+ # ==== Exceptions
1206
+ # Exception:: Generated whenever a problem occurs determining the
1207
+ # existence of the generator.
1208
+ #
1209
+ def Generator.exists?(name, connection)
1210
+ end
1211
+
1212
+
1213
+ #
1214
+ # This method creates a new generator within a database. This method
1215
+ # returns a Generator object is successful.
1216
+ #
1217
+ # ==== Parameters
1218
+ # name:: A string containing the name for the new generator.
1219
+ # connection:: A reference to the Connection object that will be used to
1220
+ # create the generator.
1221
+ #
1222
+ # ==== Exceptions
1223
+ # Exception:: Generated whenever a problem occurs creating the new
1224
+ # generator in the database.
1225
+ #
1226
+ def Generator.create(name, connection)
1227
+ end
1228
+ end
1229
+
1230
+
1231
+ #
1232
+ # This class represents a connection to the service manager for a Firebird
1233
+ # database server instance. NOTE: This class does not currently work on the
1234
+ # Mac OS X platform.
1235
+ #
1236
+ class ServiceManager
1237
+ #
1238
+ # This is the constructor for the ServiceManager class.
1239
+ #
1240
+ # ==== Parameters
1241
+ # host:: The name of the host supporting the service manager to be
1242
+ # connected with.
1243
+ #
1244
+ def initialize(host)
1245
+ end
1246
+
1247
+
1248
+ #
1249
+ # This method attaches a ServiceManager object to its host service. The
1250
+ # user name used to connect with can affect which services can be accessed
1251
+ # on the server.
1252
+ #
1253
+ # ==== Parameters
1254
+ # user:: A string containing the user name to connect with.
1255
+ # password:: A string containing the user password to connect with.
1256
+ #
1257
+ def connect(user, password)
1258
+ end
1259
+
1260
+
1261
+ #
1262
+ # This method disconnects a previously connected ServiceManager object.
1263
+ #
1264
+ def disconnect
1265
+ end
1266
+
1267
+
1268
+ #
1269
+ # This method is used to determine whether a ServiceManager object has
1270
+ # been connected.
1271
+ #
1272
+ def connected?
1273
+ end
1274
+
1275
+
1276
+ #
1277
+ # This method is used to batch execute a collection of task objects.
1278
+ #
1279
+ # ==== Parameters
1280
+ # tasks:: One or more task objects to be executed by the service manager.
1281
+ #
1282
+ # ==== Exceptions
1283
+ # FireRubyException:: Generated whenever this method is called on a
1284
+ # disconnected service manager or is a problem
1285
+ # occurs executing one of the tasks.
1286
+ #
1287
+ def execute(*tasks)
1288
+ end
1289
+ end
1290
+
1291
+
1292
+ #
1293
+ # This class represents a service manager task to add a new user to a
1294
+ # database instance. NOTE: This class does not currently work on the
1295
+ # Mac OS X platform.
1296
+ #
1297
+ class AddUser
1298
+ # Attribute accessor.
1299
+ attr_reader :user_name, :password, :first_name, :middle_name, :last_name
1300
+
1301
+ # Attribute mutator.
1302
+ attr_writer :user_name, :password, :first_name, :middle_name, :last_name
1303
+
1304
+ #
1305
+ # This is a constructor for the AddUser class.
1306
+ #
1307
+ # ==== Parameters
1308
+ # user_name:: A String containing the user name to be assigned to the
1309
+ # new user.
1310
+ # password:: A String containing the password to be assigned to the
1311
+ # new user.
1312
+ # first_name:: A String containing the first name to be associated with
1313
+ # the new user. Defaults to nil.
1314
+ # middle_name:: A String containing the middle name to be associated
1315
+ # with the new user. Defaults to nil.
1316
+ # last_name:: A String containing the last name to be associated with
1317
+ # the new user. Defaults to nil.
1318
+ #
1319
+ def initialize(user_name, password, firsts_name=nil, middle_name=nil,
1320
+ last_name=nil)
1321
+ end
1322
+
1323
+
1324
+ #
1325
+ # This method executes the add user task against a service manager.
1326
+ #
1327
+ # ==== Parameters
1328
+ # manager:: A reference to the ServiceManager object to execute the task
1329
+ # on.
1330
+ #
1331
+ # ==== Exceptions
1332
+ # FireRubyException:: Generated whenever a disconnected service manager
1333
+ # is specified or an error occurs executing the
1334
+ # task.
1335
+ #
1336
+ def execute(manager)
1337
+ end
1338
+ end
1339
+
1340
+
1341
+ #
1342
+ # This class represents a service manager task to remove an existing user
1343
+ # from a database instance. NOTE: This class does not currently work on the
1344
+ # Mac OS X platform.
1345
+ #
1346
+ class RemoveUser
1347
+ # Attribute accessor.
1348
+ attr_reader :user_name
1349
+
1350
+ # Attribute mutator.
1351
+ attr_writer :user_name
1352
+
1353
+ #
1354
+ # This is a constructor for the RemoveUser class.
1355
+ #
1356
+ # ==== Parameters
1357
+ # user_name:: A String containing the user name to be assigned to the
1358
+ # new user.
1359
+ #
1360
+ def initialize(user_name)
1361
+ end
1362
+
1363
+
1364
+ #
1365
+ # This method executes the remove user task against a service manager.
1366
+ #
1367
+ # ==== Parameters
1368
+ # manager:: A reference to the ServiceManager object to execute the task
1369
+ # on.
1370
+ #
1371
+ # ==== Exceptions
1372
+ # FireRubyException:: Generated whenever a disconnected service manager
1373
+ # is specified or an error occurs executing the
1374
+ # task.
1375
+ #
1376
+ def execute(manager)
1377
+ end
1378
+ end
1379
+
1380
+
1381
+ #
1382
+ # This class represents a service manager task to backup an existing database
1383
+ # on the Firebird server. NOTE: This class does not currently work on the
1384
+ # Mac OS X platform.
1385
+ #
1386
+ class Backup
1387
+ # Attribute accessor.
1388
+ attr_reader :backup_file, :database
1389
+
1390
+ # Attribute mutator.
1391
+ attr_writer :backup_file, :database
1392
+
1393
+ #
1394
+ # This is the constructor for the Backup class.
1395
+ #
1396
+ # ==== Parameters
1397
+ # database:: A String or File giving the path and name (relative to the
1398
+ # database server) of the main database file for the database
1399
+ # to be backed up.
1400
+ # file:: A String or File giving the path and name (relative to the
1401
+ # database server) of the back up file to be generated.
1402
+ #
1403
+ def initialize(database, file)
1404
+ end
1405
+
1406
+
1407
+ #
1408
+ # This method fetches the blocking factor to be used in generating the
1409
+ # back up. This will return nil until it has been explicitly set.
1410
+ #
1411
+ def blocking_factor
1412
+ end
1413
+
1414
+
1415
+ #
1416
+ # This method sets the blocking factor to be used in generating the
1417
+ # back up.
1418
+ #
1419
+ # ==== Parameters
1420
+ # size:: A reference to an integer containing the new back up blocking
1421
+ # factor setting.
1422
+ #
1423
+ def blocking_factor=(size)
1424
+ end
1425
+
1426
+
1427
+ #
1428
+ # This method fetches the ignore checksums setting for a Backup object.
1429
+ #
1430
+ def ignore_checksums
1431
+ end
1432
+
1433
+
1434
+ #
1435
+ # This method is used to set the indicator for whether checksum values
1436
+ # should be ignored in performing a backup.
1437
+ #
1438
+ # ==== Parameters
1439
+ # setting:: True to ignore checksums, false otherwise.
1440
+ #
1441
+ def ignore_checksums=(setting)
1442
+ end
1443
+
1444
+
1445
+ #
1446
+ # This method fetches the ignore limbo setting for a Backup object.
1447
+ #
1448
+ def ignore_limbo
1449
+ end
1450
+
1451
+
1452
+ #
1453
+ # This method is used to set the indicator for whether limbo transactions
1454
+ # should be ignored in performing a backup.
1455
+ #
1456
+ # ==== Parameters
1457
+ # setting:: True to ignore limbo transactions, false otherwise.
1458
+ #
1459
+ def ignore_limbo=(setting)
1460
+ end
1461
+
1462
+
1463
+ #
1464
+ # This method fetches the metadata only setting for a Backup object.
1465
+ #
1466
+ def metadata_only
1467
+ end
1468
+
1469
+
1470
+ #
1471
+ # This method is used to set the indicator for whether a backup stores
1472
+ # only the database metadata.
1473
+ #
1474
+ # ==== Parameters
1475
+ # setting:: True to store only metadata, false otherwise.
1476
+ #
1477
+ def metadata_only=(setting)
1478
+ end
1479
+
1480
+
1481
+ #
1482
+ # This method fetches the garbage collect setting for a Backup object.
1483
+ #
1484
+ def garbage_collect
1485
+ end
1486
+
1487
+
1488
+ #
1489
+ # This method is used to set the indicator for whether the backup will
1490
+ # undertake garbage collection.
1491
+ #
1492
+ # ==== Parameters
1493
+ # setting:: True to perform garbage collection, false otherwise.
1494
+ #
1495
+ def garbage_collect=(setting)
1496
+ end
1497
+
1498
+
1499
+ #
1500
+ # This method fetches the non-transportable setting for a Backup object.
1501
+ #
1502
+ def non_transportable
1503
+ end
1504
+
1505
+
1506
+ #
1507
+ # This method is used to set the indicator for whether backup generated
1508
+ # by the task will be platform specific.
1509
+ #
1510
+ # ==== Parameters
1511
+ # setting:: True to generate a platform specific backup, false otherwise.
1512
+ #
1513
+ def non_transportable=(setting)
1514
+ end
1515
+
1516
+
1517
+ #
1518
+ # This method fetches the convert tables setting for a Backup object.
1519
+ #
1520
+ def convert_tables
1521
+ end
1522
+
1523
+
1524
+ #
1525
+ # This method is used to set the indicator for whether external tables
1526
+ # will be converted to internal tables as part of the backup.
1527
+ #
1528
+ # ==== Parameters
1529
+ # setting:: True to convert external tables, false otherwise.
1530
+ #
1531
+ def convert_tables=(setting)
1532
+ end
1533
+
1534
+
1535
+ #
1536
+ # This method is used to execute a backup task against a service manager.
1537
+ #
1538
+ # ==== Parameters
1539
+ # manager:: A reference to the service manager to execute the backup
1540
+ # task against.
1541
+ #
1542
+ # ==== Exceptions
1543
+ # FireRubyException:: Generated whenever a disconnected service manager
1544
+ # is specified or a problem occurs executing the
1545
+ # task.
1546
+ #
1547
+ def execute(manager)
1548
+ end
1549
+
1550
+
1551
+ #
1552
+ # This method fetches the log value for a Backup task. This value will
1553
+ # always be nil until the task has been executed. After a successful
1554
+ # execution the log value should contain output from the backup task
1555
+ # generated on the server.
1556
+ #
1557
+ def log
1558
+ end
1559
+ end
1560
+
1561
+
1562
+ #
1563
+ # This class represents a service manager task to restore a previously
1564
+ # created database backup on the Firebird server. NOTE: This class does not
1565
+ # currently work on the Mac OS X platform.
1566
+ #
1567
+ class Restore
1568
+ # Attribute accessor.
1569
+ attr_reader :backup_file, :database
1570
+
1571
+ # Attribute mutator.
1572
+ attr_writer :backup_file, :database
1573
+
1574
+ # Access mode constant definition.
1575
+ ACCESS_READ_ONLY = 39
1576
+
1577
+ # Access mode constant definition.
1578
+ ACCESS_READ_WRITE = 40
1579
+
1580
+ # Restore mode constant definition.
1581
+ MODE_CREATE = 0x1000
1582
+
1583
+ # Restore mode constant definition.
1584
+ MODE_REPLACE = 0x2000
1585
+
1586
+ #
1587
+ # This is the constructor for the Restore class.
1588
+ #
1589
+ # ==== Parameters
1590
+ # file:: A String or File containing the path and name (relative to
1591
+ # the server) of the backup file to be used in the restore.
1592
+ # database:: A String or File containing the path and name (relative to
1593
+ # the server) of the database file to be restored.
1594
+ #
1595
+ def initialize(file, database)
1596
+ end
1597
+
1598
+
1599
+ #
1600
+ # This method retrieves the cache buffers setting for a Restore object.
1601
+ # This will be nil until a value is actual set.
1602
+ #
1603
+ def cache_buffers
1604
+ end
1605
+
1606
+
1607
+ #
1608
+ # This method updates the cache buffers setting for a Restore object.
1609
+ #
1610
+ # ==== Parameters
1611
+ # setting:: The new value for the object setting. Should be an integer.
1612
+ #
1613
+ def cache_buffers=(setting)
1614
+ end
1615
+
1616
+
1617
+ #
1618
+ # This method retrieves the page size setting for a Restore object.
1619
+ # This will be nil until a value is actual set.
1620
+ #
1621
+ def page_size
1622
+ end
1623
+
1624
+
1625
+ #
1626
+ # This method updates the page size setting for a Restore object.
1627
+ #
1628
+ # ==== Parameters
1629
+ # setting:: The new value for the object setting. Should be an integer.
1630
+ #
1631
+ def page_size=(setting)
1632
+ end
1633
+
1634
+
1635
+ #
1636
+ # This method retrieves the access mode setting for a Restore object.
1637
+ # This will be nil until a value is actual set.
1638
+ #
1639
+ def access_mode
1640
+ end
1641
+
1642
+
1643
+ #
1644
+ # This method updates the access mode setting for a Restore object.
1645
+ #
1646
+ # ==== Parameters
1647
+ # setting:: The new value for the object setting. This should be one
1648
+ # of Restore::ACCESS_READ_ONLY or Restore::ACCESS_READ_WRITE.
1649
+ #
1650
+ def access_mode=(setting)
1651
+ end
1652
+
1653
+
1654
+ #
1655
+ # This method retrieves the build indices setting for a Restore object.
1656
+ #
1657
+ def build_indices
1658
+ end
1659
+
1660
+
1661
+ #
1662
+ # This method updates the build indices setting for a Restore object.
1663
+ # This value affects whether the various indexes for a database are
1664
+ # restored with the restore task.
1665
+ #
1666
+ # ==== Parameters
1667
+ # setting:: True to rebuild the database indices, false otherwise.
1668
+ #
1669
+ def build_indices=(setting)
1670
+ end
1671
+
1672
+
1673
+ #
1674
+ # This method retrieves the no shadows setting for a Restore object.
1675
+ #
1676
+ def no_shadows
1677
+ end
1678
+
1679
+
1680
+ #
1681
+ # This method updates the no shadows setting for a Restore object.
1682
+ # This value affects whether shadow databases are recreated as part of a
1683
+ # restore.
1684
+ #
1685
+ # ==== Parameters
1686
+ # setting:: True to recreate shadow files, false otherwise.
1687
+ #
1688
+ def no_shadows=(setting)
1689
+ end
1690
+
1691
+
1692
+ #
1693
+ # This method retrieves the validity checks setting for a Restore object.
1694
+ #
1695
+ def check_validity
1696
+ end
1697
+
1698
+
1699
+ #
1700
+ # This method updates the validity checks setting for a Restore object.
1701
+ # This value affects whether the restore performs validity checks on the
1702
+ # database as it is restored.
1703
+ #
1704
+ # ==== Parameters
1705
+ # setting:: True to perform validity checks, false otherwise.
1706
+ #
1707
+ def check_validity=(setting)
1708
+ end
1709
+
1710
+
1711
+ #
1712
+ # This method retrieves the commit tables setting for a Restore object.
1713
+ #
1714
+ def commit_tables
1715
+ end
1716
+
1717
+
1718
+ #
1719
+ # This method updates the commit tables setting for a Restore object.
1720
+ # This value affects whether the restore commits tables as they are
1721
+ # restored.
1722
+ #
1723
+ # ==== Parameters
1724
+ # setting:: True to commit tables as they are restored, false otherwise.
1725
+ #
1726
+ def commit_tables=(setting)
1727
+ end
1728
+
1729
+
1730
+ #
1731
+ # This method retrieves the restore mode setting for a Restore object.
1732
+ #
1733
+ def restore_mode
1734
+ end
1735
+
1736
+
1737
+ #
1738
+ # This method updates the restore mode setting for a Restore object.
1739
+ # This value affects whether the restore will overwrite an existing
1740
+ # database.
1741
+ #
1742
+ # ==== Parameters
1743
+ # setting:: Either Restore::MODE_CREATE (default) or
1744
+ # Restore::MODE_REPLACE.
1745
+ #
1746
+ def restore_mode=(setting)
1747
+ end
1748
+
1749
+
1750
+ #
1751
+ # This method retrieves the use all space setting for a Restore object.
1752
+ #
1753
+ def use_all_space
1754
+ end
1755
+
1756
+
1757
+ #
1758
+ # This method updates the use all space setting for a Restore object.
1759
+ # This value affects whether restore leaves space within the database
1760
+ # file for expansion. This can be switched on for read only databases.
1761
+ #
1762
+ # ==== Parameters
1763
+ # setting:: True leave no default expansion space within the restored
1764
+ # database file, false otherwise.
1765
+ #
1766
+ def use_all_space=(setting)
1767
+ end
1768
+
1769
+
1770
+ #
1771
+ # This method is used to execute a restore task against a service manager.
1772
+ #
1773
+ # ==== Parameters
1774
+ # manager:: A reference to the service manager to execute the restore
1775
+ # task against.
1776
+ #
1777
+ # ==== Exceptions
1778
+ # FireRubyException:: Generated whenever a disconnected service manager
1779
+ # is specified or a problem occurs executing the
1780
+ # task.
1781
+ #
1782
+ def execute(manager)
1783
+ end
1784
+
1785
+
1786
+ #
1787
+ # This method fetches the log value for a Restore task. This value will
1788
+ # always be nil until the task has been executed. After a successful
1789
+ # execution the log value should contain output from the restore task
1790
+ # generated on the server.
1791
+ #
1792
+ def log
1793
+ end
1794
+ end
1795
+ end