(Engine-Level Function)
Maintained only to provide backward compatibility with legacy applications. Do not use in new code.
| Description: | Identical to DBAdd, except that it will not modify an existing record. Executes in its own thread to add a record to a VTScada database and returns an indication of parameter errors. |
| Returns: | Numeric |
Usage:  |
Script Only. |
| Function Groups: | Database and Data Source |
| Related to: | DBAdd | DBGetStream | DBListGet | DBListSize | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue |
| Threaded: | Yes |
| Format: |
DBInsert(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal]) Or DBInsert(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal1, FieldVal2, FieldVal3, …]) |
| Parameters: |
| DBSysVal | ||||||
| Required. The database value to use. This is the return value from a DBSystem call. | ||||||
| IDKey | ||||||
| Required. Any text expression that uniquely identifies the record to be created. | ||||||
| DefaultEvent | ||||||
|
Required. Any text expression containing one byte for each list in the system. Any missing bytes or bytes with values not included in the list provided, default to "do nothing to the list". Note that there is one byte for each list in the system.
|
||||||
| TimeStamp | ||||||
| Required. The time to be used for all lists that the new record is a member of. Current time will be used if this field is invalid. | ||||||
| EventCode | ||||||
|
Required. Any variable in which the event code for the function is returned. This parameter may be used to indicate completion of the function, as it will not be set to a valid value until execution is complete. It has one of the following meanings:
EventCode may be replaced by a constant or Invalid if it is not required. This parameter will not be set if there is a parameter error (see comments) |
||||||
| FieldVal | ||||||
| (or FieldVal1, FieldVal2, FieldVal3, … ) One or more parameters that are an array or a list of values for each field. FieldVal (or FieldVal1, FieldVal2, FieldVal3, … ) will be set to Invalid if not specified, if insufficient parameters are specified to fill each field in the new database record, or if the parameter is an array with insufficient entries to fill each field in the database. |
| Comments: | This function executes in the thread created by the DBSystem call, so it will not block other statements from executing. This does mean, however, that the timing for EventCode becoming valid (marking that the statement has finished executing) is unpredictable and should therefore be checked for validity prior to executing other statements that rely on this statement's results. The return value for this function indicates if any of its key parameters (DBSysVal, IDKey, DefaultEvent, or any required FieldVal) are illegal. It will immediately return a value of false (0) unless a key parameter was illegal, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in the thread created for it. If the database file has its read-only attribute set when this function is executed, it will be cleared automatically by execution of the function. |
Example:
AlarmDB = DBSystem("", "", 0, 0, 32 { key }, -3 { pressure },
3 { level }, -3 { temperature });
If Valid(AlarmDB) && ! Added;
[
Added = 1;
DBInsert(AlarmDB { Database to use },
"Tank_697" { ID key },
"+" { Add to list },
Event { Var to get event code },
Pressure, Level, Temperature { Field values }));
]
