The ts_begin_scan() function
The ts_begin_scan() function begins a scan of elements in a time series.
Syntax
ts_tscan *
ts_begin_scan(ts_tsdesc *tsdesc,
mi_integer flags,
mi_datetime *begin_stamp,
mi_datetime *end_stamp)- tsdesc
- Returned by ts_open().
- flags
- Determines how a scan should work on the returned set.
- begin_stamp
- Pointer to mi_datetime, to specify where the scan should start. If begin_stamp is NULL, the scan starts at the beginning of the time series. The begin_stamp argument acts much like the begin_stamp argument to the Clip function (Clip function) unless TS_SCAN_EXACT_START is set.
- end_stamp
- Pointer to mi_datetime, to specify where the scan should stop. If end_stamp is NULL, the scan stops at the end of the time series. When end_stamp is set, the scan stops after the data at end_stamp is returned.
Description
This function starts a scan of a time series between two time stamps.
The scan descriptor is closed by calling ts_end_scan().
The flags argument values
The flags argument
determines how a scan should work on the returned set. Valid values
for the flags argument are defined in tseries.h.
The integer value is the sum of the desired values from the following
table.
| Flag | Value | Meaning |
|---|---|---|
| TS_SCAN_HIDDEN | 512 (0x200) | Return hidden elements marked by ts_hide_elem() |
| TS_SCAN_EXACT_START | 256 (0x100) | Return NULL if the begin point is earlier than the time series origin. (Normally a scan does not start before the time series origin.) |
| TS_SCAN_EXACT_END | 128 (0x80) | Return NULL until the end timepoint of the scan is reached, even if the end timepoint is beyond the end of the time series. |
| TS_SCAN_NO_NULLS | 32 (0x20) | Affects the way elements are returned that have never been allocated (TS_NULL_NOTALLOCATED). Usually, if an element has not been allocated it is returned as NULL. If TS_SCAN_NO_NULLS is set, an element is returned that has each column set to NULL instead. |
| TS_SCAN_SKIP_END | 16 (0x10) | Skip the element at the end timepoint of the scan range. |
| TS_SCAN_SKIP_BEGIN | 8 (0x08) | Skip the element at the beginning timepoint of the scan range. |
| TS_SCAN_SKIP_HIDDEN | 4 (0x04) | Skip hidden elements. |
Returns
An open scan descriptor, or NULL if the scan times are both before the origin of the time series or if the end time is before the start time.
Example
See the ts_interp() function, in The Interp function example, for an example of the ts_begin_scan() function.