DBListSize

Description:              This function executes in its own thread to retrieve the size of a certain list in a VTS database and returns an indication of parameter errors.

Returns:                    Boolean

Usage:                       Script

Format:                      DBListSize(DBSysVal, Result, List, Method [, Events, IDKey, Filters])

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

                                    Result     { Variable (return value) }  { required }  { no default }
          A variable in which the resulting value will be stored.

                                    List     { varies }  { required }  { no default }
          Any numeric value or array of numeric values that define(s) the list(s) to search:

 

                             The database and transaction log cannot be combined with other lists.

                                    Method    { numeric }  { required }  { no default }
          Any numeric expression that determines how filtering is done. This parameter is one or a combination of the following values:

 

                             The filtering parameters follow (in the specified order), with only those that are applicable being included.

                                    Events     { text }  { optional }  { no default }
          An optional parameter used for filtering the records in the list and should only be included if Method designated event filtering. This value is a text string containing one byte for each list in the system; any missing bytes default to all for that list, while bytes with values not included in the list below default to no matches (i.e. nothing will be found). Note that there is one byte for each list in the system, not for each list that has been selected by the List parameter.

                             If the transaction log is being used (List = 0), the following codes are compared with the Event field of each record:

                             If one of the lists is being used (List > 0), the following codes are used:

                                    IDKey     { text }  { optional }  { no default }
          An optional parameter used for designating the record(s) to use and should only be included if the parameter Method designates ID key filtering. This is any text expression and can contain the wildcard characters "*" and "?".

                                    Filters     { varies }  { optional }  { no default }
          An optional parameter that designates the record(s) to use to filter the resulting list by using logical AND or, OR and checking for field matches; it should only be included if the parameter Method designates record value filtering.

                             At its simplest, this parameter may hold a 1-dimensional array with 2 or 3 numeric elements:

 

                             The comparison value is a numeric value or expression that indicates the type of comparison to be made, and may be omitted if desired; in this case, the comparison will be taken to mean "is equal to". Valid values for this third element are as follows:

 

                             Notice that the comparison values of 3, 7, 11, and 15 are really only useful when the field value is a text string. For example, if you want to get only those entries whose value starts with "d", the field value should be "d*", and the comparison value should be 3. If however, you want all entries that don't start with "d", the field value should still be "d*", with a comparison value of 7.

                             If a more detailed filtering criterion is required, a 2-dimensional array may be used, where additional rows are added, each with the same elements as the first ([n][0] is field number, [n][1] is limiting value, [n][2] is comparison type). All rows will then be ANDed together to form the filtering statement. Once again, the third column may be omitted entirely, however, if it exists it must have valid values in all rows.

                             The most detailed filtering array occurs when an ORing of field specifications is also required. In this case, this parameter is a 1-dimensional array, where each element contains a pointer to an array as described previously. The elements in each AND array will be ANDed together, then the results from these ANDed arrays will be ORed.

                             VTS differentiates between the various options for this parameter by checking its first element. If it is not a pointer, then the parameter is assumed to contain a single AND array directly (i.e. no ORing is performed); it should only be included if Method designated record value filtering.

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 Result becoming valid is unpredictable and should therefore be checked for validity prior to being used.

                             The return value for this function indicates if any of its key parameters (DBSysVal, List, or Method) are invalid:

                             If all of the key parameters are valid, DBListSize will immediately return a value of false (0).

                             If any of the key parameters are invalid, DBListSize will not perform the required operation, and will instead immediately return a value of 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.

For information about the standard alarm lists in VTS see Alarm Manager Service.

Example:

db = DBSystemDBSystem(dbFile, "", 0, 0, 64 { key }, -3 { field 1 });

If Valid(db) && ! gotSize;

[

  gotSize = 1; 

  DBListSize(db { Database to use }, 

  size { Resultant value }, 

  2 { List number to use }, 

  0 { Method - include everything } 

  { Events parameter not required } 

  { IDKey parameter not required } 

  { Filters parameter not required }); 

]

If there is any doubt as to the validity of the parameters and further statements rely on size becoming valid, the following version of the script might be more appropriate.

If Valid(db) && ! gotSize;

[

  gotSize = 1; 

  IfThen(DBListSize(db , size, 2, 0 ), 

  size = 0; 

  ); 

]

See Also:

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