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.