DBGetStream

Description: This function executes in its own thread to convert a database to a stream, and returns an indication of parameter errors.

Returns: Numeric

Usage: Script

Format: DBGetStream(DBSysVal, Stream [, Timestamp])

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

Stream { Stream } { required } { no default }
Any variable in which the stream containing the database will be returned.

Timestamp { Timestamp } { optional } { no default }
An optional parameter that is any numeric expression indicating the earliest timestamp to include in the stream; only database records with date/time values greater than or equal to this parameter will be returned.

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

The return value for this function indicates if its key parameter (DBSysVal) is invalid:

If DBSysVal is valid, DBGetStream will immediately return a value of false (0).

If DBSysVal is invalid, DBGetStream 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 output variable (DBSysVal) is invalid, DBGetStream will not perform the required operation, and will instead immediately return a value of 1.

Since the value of the Stream parameter is created from a database's file, the DBSystem function that created the database had to have a valid first parameter (the file name in which the database contents are stored).

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:

db = DBSystem("", "", 0, 0, 32 { key }, -3 { pressure },

3 { level }, -3 { temperature });

If Valid(db) && ! done;

[

done = 1;

DBGetStream(db { Database to use },

result { Returned stream value });

]