[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

isigopen

 
int isigopen(char *record, WFDB_Siginfo *siarray, int nsig)
Return:

>0
Success: the returned value is the number of input signals (i.e., the number of valid entries in siarray)
0
Failure: no input signals available
-1
Failure: unable to read header file (probably incorrect record name)
-2
Failure: incorrect header file format

This function opens input signal files for a selected record. If record begins with `+', previously opened input signal files are left open, and the record name is taken to be the remainder of record after discarding the `+'. Otherwise, isigopen closes any previously opened input signal files, and takes all of record as the record name. If the record name is `-', isigopen reads the standard input rather than a `hea' file. Siarray is a pointer to an array of WFDB_Siginfo structures (see section 3.1 Signal Information Structures), one for each signal to be opened.

As a special case, if nsig is 0, siarray can be NULL. In this case, isigopen closes any open input signals, then returns the number of signals in record without opening them. Use this feature to determine the amount of storage needed for signal-related variables, as in the example below, or to force open input signal files to be closed without closing open annotation or output signal files. This action also sets internal WFDB library variables that record the base time and date, the length of the record, and the sampling and counter frequencies, so that time conversion functions such as strtim that depend on these quantities will work properly.

If nsig is greater than 0, isigopen normally returns the number of input signals it actually opened, which may be less than nsig but is never greater than nsig. The caller must allocate storage for the WFDB_Siginfo structures; isigopen will fill them in with information about the signals. Signal numbers are assigned in the order in which signals are specified in the `hea' file for the record; on return from isigopen, information for signal i will be found in siarray[i]. For example, we can read the gain attributes of each signal in record `100s' like this:

 
#include <stdio.h>
#include <wfdb/wfdb.h>

main()
{
    int i, nsig;
    WFDB_Siginfo *siarray;

    nsig = isigopen("100s", NULL, 0);
    if (nsig < 1)
        exit(1);
    siarray = (WFDB_Siginfo *)malloc(nsig * sizeof(WFDB_Siginfo));
    nsig = isigopen("100s", siarray, nsig);
    for (i = 0; i < nsig; i++)
        printf("signal %d gain = %g\n", i, siarray[i].gain);
    exit(0);
}

(See http://www.physionet.org/physiotools/wfdb/examples/pgain.c for a copy of this program.)

This program, unlike the example in the previous chapter, does not assume that the number of signals is known. The first invocation of isigopen determines this number (and the program quits if there are no signals). Next, the program allocates the array for the signal information, and then it opens the signals using the second invocation of isigopen, passing in the pointer siarray and the number of signals determined from the first call (nsig).

An error message is produced if isigopen is unable to open any of the signals listed in the header file. It is not considered an error if only some of the signals can be opened, however. A signal will not be opened if its signal file is unreadable, if an input buffer cannot be allocated for it, or if opening all of the signals in its group would exceed the limits defined by nsig. (Note, however, that most records have only one signal group; as a consequence, isigopen fails if nsig is less than the total number of signals in such cases.) If necessary, the caller can inspect the file names and signal descriptions in siarray to determine which signals were opened; see section 3.1 Signal Information Structures. Several of the example programs in chapter 6 illustrate the use of isigopen; for example, see section Example 5: Reading Signal Specifications.

If nsig is less than 0, isigopen fills in up to -nsig members of siarray, based on information from the header file for record, but no signals are actually opened. The value returned in this case is the number of signals named in the `hea' file. Note, however, that there is no guarantee that all (or indeed any) of the signals named in the `hea' file are available to be opened. The features described in this paragraph were first introduced in version 4.4 of the WFDB library.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

George B. Moody (george@mit.edu)