annstr, anndesc, and ecgstr

char *annstr(int code)
char *anndesc(int code)
char *ecgstr(int code)

Return:

(char *)

pointer to a printable string that describes the code, or NULL

These functions translate the annotation code specified by their argument into a string (see section Annotation Codes). Illegal or undefined codes are translated by annstr and ecgstr into decimal numerals surrounded by brackets (e.g., `[55]'); anndesc returns NULL in such cases. The strings returned by annstr are mnemonics (usually only one character), which may be modified either by setannstr or by the presence of modification labels in an input annotation file (see section annstr, anndesc, and ecgstr). The strings returned by anndesc are brief descriptive strings, usually those given in the table of annotation codes (see section Annotation Codes). The strings returned by ecgstr are usually the same as those returned by annstr, but they can be modified only by setecgstr, and not by the presence of modification labels as for annstr. The intent is that ecgstr should be used rather than annstr only when it is necessary that a fixed set of mnemonics be used, independent of any modification labels.

Here is a little program that prints a table of the codes, mnemonic strings, and descriptions:

#include <stdio.h>
#include <ecg/db.h>
#include <ecg/ecgcodes.h>

main()
{
    int i;

    printf("Code\tMnemonic\tDescription\n");
    for (i = 1; i <= ACMAX; i++) {
        printf("%3d\t%s", i, annstr(i));
        if (anndesc(i) != NULL)
            printf("\t\t%s", anndesc(i));
        printf("\n");
    }
}

ACMAX is defined in `<ecg/ecgcodes.h>'. The range from 1 through ACMAX includes all legal annotation codes; if you run this program, you will find some undefined but legal annotation codes in this range. See section Example 3: An Annotation Printer, for another illustration of the use of annstr. (annstr and anndesc were first introduced in DB library version 5.3.)

strann and strecg

int strann(char *string)
int strecg(char *string)

Return:

(int)

annotation code

These functions translate the null-terminated ASCII character strings to which their arguments point into annotation codes. Illegal strings are translated into NOTQRS. Input strings for strann and strecg should match those returned by annstr and ecgstr respectively. See section Example 9: A Signal Averager, for an illustration of the use of strann. (strann was first introduced in DB library version 5.3.)

setannstr, setanndesc, and setecgstr

int setannstr(int code, char *string)
int setanndesc(intcode, char *string)
int setecgstr(int code, char *string)

Return:

0

Success

-1

Failure: illegal code

These functions modify translation tables used by functions that convert between annotation codes and strings. setannstr modifies the table shared by annstr and strann; setanndesc modifies the table used by anndesc; and setecgstr modifies the table shared by ecgstr and strecg. They may be used to redefine strings for defined annotation codes as well as to define strings for undefined annotation codes. For example, setannstr(NORMAL, "\\267") redefines the string for normal beats as a PostScript bullet, `*' (NORMAL is defined in `<ecg/ecgcodes.h>'). These functions do not copy their string arguments, which must therefore be kept valid by the caller.

An important difference between setannstr (or setanndesc) and setecgstr is that annopen and dbinit insert modification labels in any output annotation files that are created after invoking setannstr or setanndesc; setecgstr does not have this side effect. By using setannstr before annopen, a DB application may create annotation files with self-contained code tables, which can be read properly by other DB applications without the need to inform them explicitly about non-standard codes. For this scheme to work as intended, all custom code mnemonics and descriptions must be defined before the output annotation files are opened.

By passing a negative value as code to setannstr or setanndesc, the translation for -code can be modified without triggering the generation of a modification label. This feature can be useful for programs that use alternate sets of mnemonics or descriptions for speakers of different languages.

Note that it is possible, though not desirable, to define identical strings for two or more codes; the behavior of strann and strecg in such cases is implementation-dependent. (setannstr and setanndesc were first introduced in DB library version 5.3.)

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