label: Manual Page

LABEL

NAME

lab_store, lab_reset, lab_initfile, lab_getmatch, lab_gettext - text label routines for data sets

SYNOPSIS


char    *lab_store(item)
struct item_header *item;

void    lab_reset()

void    lab_initfile(filename)
char    *filename;

char    *lab_getmatch(code)
char    *code;

char    *lab_gettext(history)
char    *history;

OVERVIEW

These routines provide a simple mechanism for accessing and describing data sets using short codes and textual descriptions rather than the more formal mechanisms of item numbering and item histories. The routines lab_getmatch() and lab_gettext() access a "labels" file where the mappings between "short codes" and "history matches", and the mappings between "history matches" and "text descriptions" are kept, see labels(SFS5).

LAB_STORE

This routine adds an item history to an internal database of histories for the file. It returns the "expanded history" for the item, which is simply the item history but with all referred items (recursively) expanded. For example if the item list was:


	1.01 inwd
	2.01 inwd(freq=10000)
	3.01 tx(2.01)
	4.01 lxp(1.01,3.01)

then the expanded histories would be:

	1.01 inwd
	2.01 inwd(freq=10000)
	3.01 tx(inwd(freq=10000))
	4.01 lxp(inwd,tx(inwd(freq=10000)))

Notice that to expand the history for an item, lab_store requires to be passed the histories of all earlier items in the file. The expanded histories can be obtained as the file is processed, or they can be set up for the whole file with a simple loop, like:


	fid = sfsopen(filename,"r",NULL);
	while (sfsnextitem(fid,&item)) lab_store(&item);

or with a call to the routine lab_initfile, (below).

LAB_RESET

This routine resets the internal database of histories, so that another file can be processed within the same program.

LAB_INITFILE

This routine scans the items in the given file, and calls lab_store for each item.

LAB_GETMATCH

This routine takes a short code specifying a type of data set and returns a string match expression that selects appropriate items on the basis of their expanded history. The string match expressions are stored in a "labels" file and expect to be used with the string match function histmatch(SFS3). The routine returns NULL if the code cannot be found. For the structure of the labels file see labels(SFS5).

LAB_GETTEXT

This routine takes an expanded item history and returns a text description of the item. The text descriptions are stored in the "labels" file, and the first text description is returned which matches the given history. The routine returns NULL if no text desciption can be found. For the structure of the labels file see labels(SFS5).

FILES

SFSLABEL Environment variable containing labels file search path. (files separated by ";"). If SFSLABEL is not present, the default file: "SFSBASE/data/labels" is used.

VERSION/AUTHOR

2.0 - Mark Huckvale