DBAdd

Description:              This function executes in its own thread to add a record to a VTS database and returns an indication of parameter errors.

Returns:                    Numeric

Usage:                       Script

Format:                      DBAdd(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal])

                             Or

                             DBAdd(DBSysVal, IDKey, DefaultEvent, EventCode [, FieldVal1, FieldVal2, FieldVal3, …])

Parameters:             DBSysVal    { handle }  { required }  { no default }
          The database value to use; this is the return value from a DBSystem call.

                                    IDKey     { text }  { required }  { no default }
          Any text expression that uniquely identifies the record to be created.

                                    DefaultEvent     { text }  { required }  { no default }
          Any text expression containing one byte for each list in the system; any missing bytes or bytes with values not included in the list below default to "do nothing to the list". Note that there is one byte for each list in the system.

                                    EventCode     { Variable (return value) }  { required }  { no default }
          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 never be set if there is a parameter error (see comments)

                                    FieldVal (or FieldVal1, FieldVal2, FieldVal3, … )

                                        { varies }  { required }  { no default }
Optional parameter(s) that is(are) an array or a list of values that define the value for each field. FieldVal (or FieldVal1, FieldVal2, FieldVal3, … ) is set to Invalid if

•          not specified,

•          insufficient parameters to fill each field in the new database record are specified, 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 invalid. It will immediately return a value of false (0) unless a key parameter was invalid, 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 record that is to be added already exists (i.e. its IDKey duplicates one already in the system), the field values of the pre-existing record are updated by those defined in the FieldVal parameter(s).

                             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; 

  DBAdd(AlarmDB { Database to use }, 

        "Tank_697" { ID key }, 

        "+" { Add to list }, 

        event { Var to get event code }, 

        pressure, level, temperature 

  { Field values })); 

]

See Also:

DBAdd | DBGetStream | DBListGet | DBListSize | DBSystem | DBTransaction | DBUpdate | DBValue