DbServer Class (Typed)

Object
  DataServer
    DbServer
      AdsSQLServer

Request Example View Source

The following table lists the properties and methods that reflect the currently active selection: Several Xbase database commands provide a number of options for specifying the scope of the operation through keywords: ALL, REST, NEXT nRecords, RECORD nRecord, as well as through FOR and WHILE clauses. The semantics of these clauses, and how they interact when several are specified, are described under "Using DBF Files" in the Programmer's Guide. The corresponding DBServer methods (like Average(), AppendDB(), CopyDB(), Sort(), Sum(), Total(), and others) allow the specification of a FOR clause, a WHILE clause and a scope as arguments in the invocation. In addition, it is possible to set up a "general server scope" using simple assigns (the corresponding accesses are also provided). This general scope applies whenever one of these bulk processing methods is invoked without an explicit scope. This approach can in many cases be more convenient. For example, to delete the next five records: For example, to delete all the remaining records: To count the number of Smiths in New Jersey: Remember to restore the scope afterwards: the scope is persistent and applies to all following scope-based methods until reset. The convenience of this style of specifying a scope comes with the danger of leaving it active for too long. The scope can be reset with the DBServer:ClearScope() method, or by assigning NIL to the individual components. The general server scope can be set with: Property Meaning ForBlock A string or codeblock specifying the FOR condition. Scope DBSCOPEALL, DBSCOPEREST or a number nRecords (meaning NEXT nRecords). WhileBlock A string or codeblock specifying the WHILE condition. Note that there is no provision for specifying a specific record number with this approach. There is rarely a need to process a specific record (e.g., the average of the salary of record 5). In cases where there is, such as for Delete(), use RecNo := n, GoTo(n) or Seek(Value) to position the server, and then invoke Delete(). The methods that are subject to the general server scope are: The default scope is, of course, "no scope," so these methods have the same default behavior as the corresponding commands and functions. Most of them process all records or all remaining records, depending on how the scope is defined; those for which the default is "the current record" also have corresponding "all" methods: But note that if a selective relation has been specified, the default source scope is the selection, not the entire file. Thus, we have four levels of inheritance with regard to the scope of an operation: 1. The scope that explicitly specified through arguments of the call 2. If none was provided, the scope that is set through the ForBlock, WhileBlock and Scope properties 3. If none was set, the selection specified with the selective relation 4. If no selective relation is active, the entire file The exceptions Delete() and Recall() use options 1 and 2, then default to the current record. DeleteAll() and RecallAll() apply to the current selection, if any; otherwise, to the entire file. Of course, a selection scope is not relevant to the Append... methods, for which the conditions apply to the source file, not this server. The DBServer Editor generates a subclass of the generic DBServer class, one with specific information such as file names and virtual fields created as access/assign methods. It is not possible to use the DBServer class to create a database file; the file must exist before a server can be opened on it. To create a database file, use the DBCreate() (recommended) method, the VODBCreate() function, or the DBServer Editor. This section describes the shared access and aliasing mechanisms used when creating multiple DBServer work areas or servers, as well as hybrid object/procedural operation. Work area Creating a DBServer object opens a database in a work area. There is no provision for specifying whether a new or existing work area should be used; the DBServer always uses a new work area. After the instantiation, the new work area is not selected; the work area that was selected before the instantiation remains active. Thus, traditional database commands and functions issued after the instantiation of the DBServer does not apply to the newly opened database. The proper way to operate on the new DBServer is through its methods. Shared access Creating two DBServer objects on the same database file is equivalent to opening the same file in two different work areas. The two servers (work areas) each maintain its own position and record locks, and operate as two users sharing access to the same file. To allow creating two servers on the same database file (opening the same file in two work areas), they must, of course, be opened in shared mode; otherwise the second attempt produces a sharing violation. However, this does not raise an error condition, it simply stores an invalid status of the object. Use the DBServer:Status or DBServer:Used properties after the instantiation to verify if a file was successfully opened. Shared mode can be specified as an instantiation parameter (for example, SetExclusive(FALSE) in the Start() function) or as a system default (see DBServer:Init()). Alias When using the methods of the DBServer to work with the database, an alias is not needed; the DBServer object provides the handle by which the database is referenced. The alias has no role in operating with a DBServer object, but internally the system needs a unique alias for every work area. The DBServer automatically constructs a unique alias. If the file is not open in any other work area or server, it uses the file name as the alias in the traditional manner, but if the file is already open, it creates a unique alias by appending a number. Thus, opening the CUSTOMER file twice would produce the two aliases #Customer and #Customer_1. The only reason for explicitly using the alias is to perform "hybrid" operation, using traditional, procedural operations with commands or functions on a DBServer object. This practice is strongly discouraged, however. Because the DBServer object may not be aware of what is done through the commands, DBServer methods can malfunction after use of procedural commands. (For more details, see "Using DBF Files" in the Programmer's Guide.) It is possible to retrieve the automatically generated alias from the DBServer object, to enable selection of the work area as the focus of procedural database operations: Most of the changes we made in the RDD classes were made to improve the speed of the RDD classes. One change in particular could influence your application: in the old implementation Visual Objects was restoring the ‘current workarea’ after each DbServer:Method call. This is only useful if you are mixing Object Oriented DBF access with traditional work area oriented DBF access. If all you do is Object Oriented DBF access, the work area switching is unnecessary and may have a negative impact on your applications performance. Therefore we have added a switch to the RDD classes that allows you do enable/disable this restore mechanism. The default for Visual Objects 2.8 is to NOT restore the workarea. The switch is in the function: This is a global switch, which changes the behaviour of the DBServer class. The default value of the lEnable switch is FALSE which means that workarea restoring is disabled. As a result of this at the end of each DbServer method the current workarea is the workarea of the DBServer. If you set the lEnable flag to TRUE every DBServer method restores the workarea at the end of the method to the value of the work area at the beginning of the method. This is the old behavior, but costs some extra time. The return value of DbSetRestoreWorkarea () is the previous value. If lEnable is NIL the switch is not set and SetRestoreWorkarea() returns only the current value. DbSetRestoreWorkarea () also changes the internal behaviour of the new internal function __DBSetSelect(siNew). If you call DbSetRestoreWorkarea (TRUE) which is the default __DBSetSelect() is identical to VODBSetSelect(), if you call DbSetRestoreWorkarea (FALSE) DBSetSelect() is empty and do nothing.