2.4 Non-Sequential Access to WFDB Files

The next three functions permit random access to signal and annotation files. It is not possible, however, to skip backwards on piped input.

isigsettime

int isigsettime(WFDB_Time t)

Return:

0

Success

-1

Failure: EOF reached or improper seek

This function resets the input signal file pointers so that the next samples returned from getvec will be those with sample number |t|. Only the magnitude of t is significant, not its sign; hence values returned by strtim can always be used safely as arguments to isigsettime (see section timstr and strtim). This function will fail if a pipe is used for input and |t| is less than the current sample number. See section Example 7: A General-Purpose FIR Filter, and see section Example 9: A Signal Averager, for illustrations of the use of isigsettime.

isgsettime

int isgsettime(WFDB_Group sgroup, WFDB_Time t)

Return:

0

Success

-1

Failure: EOF reached or improper seek

-2

Failure: incorrect signal group number specified

This function does the job of isigsettime, but only for the signal group specified by sgroup. This function may be of use if more than one record is open simultaneously (see section Simultaneous Access to Multiple Records).

tnextvec

WFDB_Time tnextvec(WFDB_Signal s, WFDB_Time t)

Return:

>= 0

Time of the next valid sample of signal s at or after t

-1

Failure: EOF reached or improper seek

This function resets the input signal file pointers so that the next samples read by getvec will include the next valid sample of the specified signal s occurring at or after t. Use tnextvec to skip lengthy gaps in a signal of interest efficiently.

iannsettime

int iannsettime(WFDB_Time t)

Return:

0

Success

-1

Failure: EOF reached or improper seek

-3

Failure: unexpected physical end of file

This function resets the input annotation file pointers so that the next annotation read by getann from each input annotation file will be the first occurring on or after sample number |t| in that file. Only the magnitude of t is significant, not its sign; hence values returned by strtim can always be used safely as arguments to iannsettime (see section timstr and strtim). This function will fail if a pipe is used for input and |t| is less than the time of the most recent annotation read from the pipe. See section Example 9: A Signal Averager, for an illustration of the use of iannsettime.

sample and sample_valid

WFDB_Sample sample(WFDB_Signal s, WFDB_Time t)
int sample_valid(void)

Return:

n

(from sample): The value (in raw adus) of sample number t in open signal s,if successful, or the value of the previous successfully read sample.

1

(from sample_valid): The most recent value returned by sample was valid

0

(from sample_valid): The most recent t given to sample follows the end of the record

-1

(from sample_valid): The most recent value returned by sample was invalid (because signal s is not available at time t)

The sample function allows the caller to read samples of the currently open input signals in any order. The first argument is a signal number (a non-negative integer between 0 and nsig-1, where nsig is the number of open input signals), and the second is a time, expressed as a non-negative sample number. If sample is invoked with valid input arguments, the companion function sample_valid returns 1.

The sample_valid function can be used to check the results of the most recent invocation of sample. If sample_valid returns 1, the latest value returned by sample is valid. sample_valid returns 0 if sample has most recently returned a padded value following the end of the record. This allows code that uses sample to use the condition ‘sample_valid() != 0’ (or simply ‘sample_valid()’ to determine if more samples are available. If sample_valid returns -1, the most recent value returned by sample was WFDB_INVALID_SAMPLE (because the requested signal s was unavailable at the requested time t). Use the condition ‘sample_valid() > 0’ to check if the most recent value returned by sample is a valid value (e.g., suitable for inclusion in a running average or similar calculation).

For an example of the use of sample and sample_valid, see section Example 7: A General-Purpose FIR Filter.

Be sure to call wfdbquit before exiting from any program that uses sample, to be certain that dynamically allocated memory used by sample is freed.