isigopen

int isigopen(char *record, DB_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 `header' file. Siarray is a pointer to an array of DB_Siginfo structures (see section Signal Information Structures), one for each signal to be opened. The number of DB_Siginfo structures in siarray, nsig, need never be greater than DB_MAXSIG (a constant defined in `<ecg/db.h>'); 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 DB_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 `header' 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:

...
static DB_Siginfo s[DB_MAXSIG];
int i, nsig;

nsig = isigopen("100s", s, DB_MAXSIG);
for (i = 0; i < nsig; i++)
    printf("signal %d gain = %g\n", i, s[i].gain);
...

Notice that the for loop is never executed if isigopen encounters an error, since nsig is less than 1 in such cases. The array of DB_Siginfo structures is declared static, a practice that is recommended for all arrays and data structures of any substantial size, to avoid run-time stack overflow.

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 or DB_MAXSIG. (On existing CD-ROMs containing database records, there is only one signal group for each record; as a consequence, isigopen fails if nsig is less than the number of available signals while attempting to read a CD-ROM record.) If necessary, the caller can inspect the file names and signal descriptions in siarray to determine which signals were opened; see section 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 not positive, 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 `header' file. Note, however, that there is no guarantee that all (or indeed any) of the signals named in the `header' file are available to be opened. The features described in this paragraph were first introduced in version 4.4 of the DB library.

As a special case, if nsig is 0, siarray can be NULL. This can be useful to force open input signal files to be closed without closing open annotation or output signal files.

Go to the first, previous, next, last section, table of contents.