DBSystem

(Engine-Level Function)

Maintained only to provide backward compatibility with legacy applications. Do not use in new code.

Description: Creates a VTScada database and returns its value. The maximum field length is 65,523 characters. If the field length is longer than 65,523 characters, the DBSystem call will return invalid.
Returns Numeric
Usage: Steady State only.
Function Groups: Database and Data Source
Related to: DBAdd | DBInsert | DBGetStream | DBListGet | DBListSize | DBRemove | DBTransaction | DBUpdate | DBValue
Format: DBSystem(DBFile, DBTransFile, MaxTrans, NumLists, IDKeySize, FieldAttribs)

Or

DBSystem(DBFile, DBTransFile, MaxTrans, NumLists, IDKeySize, FieldAttrib1, FieldAttrib2, FieldAttrib3)
Parameters:  
DBFile   
Required. A text expression giving the file in which to store the database information. If this parameter is invalid or is a null text string (""), no file is created and the database is reconstructed every time the system starts. DBFile can be an array containing 1 or 2 file names or streams. On startup, the second stream will be brought into sync with the first. The first is only read to initialize the database system. Both streams are maintained while the system is running.

Note that the value for this parameter may not be changed while the DBSystem call is active (i.e. the file cannot change) - any changes will be ignored.
DBTransFile   
Required. A text expression giving the file in which transactions are logged. If this parameter is invalid or is a null text string (""), no file is created and no transaction logging is done. Unlike the DBFile parameter, the value of this parameter may be changed even while the DBSystem function is active (i.e. the file is dynamic).
MaxTrans   
Required. Any numeric expression giving the maximum number of transactions to be stored in the transaction log file.
NumLists   
Required. Any numeric expression giving the number of memory lists to be maintained. The valid range is from 0 to 255.
IDKeySize   
Required. Any expression that designates the maximum length for the ID key. This affects the size of the files and the database stored in memory.
FieldAttribs   
Required. Either an array or a series of parameters that defines what type and size the fields are. The number of parameters or array entries determines how many fields there are. The valid field types are

FieldAttribs

Field Type

Attribute

-4 

Indicates a VTScada value field.

Any VTScada value may be written, but will only go into the in-memory copy of the database. The disk record will have a zero length field.

-3 

Double precision float

(8 bytes)

-2 

Long integer

(4 bytes)

-1 

Short integer

(2 bytes)

0 

Indicates a Status field

.

1 or more 

Text

(number defines length)
Comments: This function is not threaded, however, it creates a thread inside of which the database value referring to the database system requested is accessed. All other database functions (those beginning with "DB"), except for DBValue, do not create their own thread, but will execute in the thread created by this function. This thread will exist for as long as the DBSystem statement remains active (i.e. until a state change occurs). For this reason, the state containing the DBSystem call must remain active until all other database statements have finished executing. The statement responsible for a state change should therefore trigger only when all results from all statements accessing this database are valid.

WARNING: There must only be one DBSystem function acting on a file at any given time, whether the file is used as the DBFile or the DBTransFile parameter. If more than one DBSystem function is affecting the same file, it may become corrupted, even if one of the database handles is only used to read information from the database.

 

The database system produced by this function consists of three primary parts

  • A memory database
  • A transaction log file
  • From 0 - 255 user specified lists

The memory database, as the name implies, is stored only in memory, and is created at the exact moment when the DBSystem function is first executed. The database value returned by this function remains valid as long as the statement is active.

The records in the database have three or more fields as follows:

  • The IDKey field - a unique text identifier for the record.
  • The Status field - a series of bytes, one for each of the user specified lists, that indicates which lists the record is part of.
  • Any other additional fields which have been designated to exist by the user.

For each ID key there is only one record in the database. This is not the case with the transaction log (discussed later in this topic). In the case of the database that is used to maintain the VTScada alarm system, each alarm has a single record in the database.

Although the database is not considered to be a list, it is loosely described as one in such statements as DBListGet, where a value of -1 for the List parameter will use the database rather than one of the user specified lists.

The transaction log is a log file that is saved to disk. For this reason, the larger it becomes the longer it takes to access records from the transaction log. The fields of the transaction log's records are similar to those stored in the database:

  • The IDKey field - a unique text identifier for the point associated with the record.
  • The Event field - a series of bytes, one for each of the user specified lists, that indicates the event or transaction that has just occurred.
  • The Time field - a float value that gives the time of the event, or a user written time value.
  • Any other additional fields which have been designated to exist by the user.

Like the database, it is not really considered a list, however in the DBListGet statement, a value of 0 in the List parameter will use the transaction log rather than one of the user specified lists.

The log file differs from the memory database in that for each ID key, there may exist none, one or many records that use the same key. This is because every transaction done by means of the DBTransaction statement is stored in a record in the transaction log.

The lists used by the database system are virtual lists, which means that they do not exist as actual entities of the system, but rather are composed of the records belonging to the database. The Status field of each record in the database will have exactly the same number of bytes as there are lists. This field will designate which list or lists the record is a member of. In the case of the VTScada alarm system, there are three lists, the active, unacknowledged and disabled alarm lists.

If the user wishes to use this database system simply as a storage device, rather than in a complicated series of lists and transactions like the VTScada alarm system, the NumLists parameter in this function may be set to 0 - no lists will be created. Also, the DBTransFile parameter may be set to invalid, thus disabling transaction logging and causing the transaction log file to not be created.

If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by the function becoming active.

Example:

  DbSysVal = DBSystem(dbFile { Name of database file },
                      "" { No transaction log }, 
                      0, 0 { No log, no lists }, 
                      65 { No. of chars in key }, 
                      16, 1 { No. of chars in fields 1, 2 }, 
                      3 { Field 3 is float }, 
                      1 { Field 4 is short (integer) });