(Engine-Level Function)
Maintained only to provide backward compatibility with legacy applications. Do not use in new code.
| Description: | Executes in its own thread to retrieve the size of a certain list in a VTScada database and returns an indication of parameter errors. |
| Returns: | Boolean |
Usage:  |
Script Only. |
| Function Groups: | Database and Data Source |
| Related to: | DBAdd | DBInsert | DBGetStream | DBListGet | DBRemove | DBSystem | DBTransaction | DBUpdate | DBValue |
| Threaded: | Yes |
| Format: |
DBListSize(DBSysVal, Result, List, Method [, remaining parameters vary according to Method value]) |
| Parameters: |
| DBSysVal | ||||||||
| Required. The database value to use. This is the return value from a DBSystem call. | ||||||||
| Result | ||||||||
| Required. A variable in which the resulting 1 or 2 dimensional array will be stored. | ||||||||
| List | ||||||||
|
Required. 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 | |||||||||||||||||||||
|
Required. Any numeric expression that determines how filtering is done. This parameter is one or a combination of the following values
Note that the ability to filter for a supplied date range applies only to VTScada database log files. An example of the format of the supplied date range can be found in the Examples section of this topic. The filtering parameters follow (in the specified order), with only those that are applicable being included. |
| Events | ||||||||||||||||||||||||||||||||||||||||||||||
|
Optional. 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 following list 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 one of the lists is being used (List > 0), the following codes are used:
|
| IDKey | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Optional. 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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Optional. 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.
If (and only if) you are creating an alarm filter that is specifically for use only with the alarm name field (\AlarmNameField -2), then two additional parameters are required, having the following values. This allows the translation of the alarm UniqueID, which is held in the record, to the friendly name used in the search string.
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:
Note that the comparison values of 3, 7, 11, and 15 are 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. VTScada 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. If no filter being used at all, the function reports the number of records stored in the header of the underlying formatted file class, rather than counting records one by one. 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 VTScada 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;
);
]
If filtering for a supplied date range:
DBListSize(DBLogVal, MatchingRecords, 0 { Log list },
16 { date range method}, ClientTime, ServerTime)
